subflag-rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da40f567a605d55076aaeabed1edd404bb41ba2a1703c56595e42611ebf4aaa4
-  data.tar.gz: 39df667c30500ebf560e90694213f05b479d60f488575c7f2503409bc640222d
+  metadata.gz: bd3dfb04635e013ed8a9da2282150acf511c8704aace3c439a06f7e5dd0ac24a
+  data.tar.gz: adc804044699b6cea75d8b44fc742d08f2a96b24092a8e66d19b419f41c45fa1
 SHA512:
-  metadata.gz: 0bb2499ecf945fb2586918f5c3e57cdda5e6ce2f143eb4b6d1d674370412ccee6f6e8fe5d992705ac4b0b28de88465ebe7e140fad1a2c71f691982ebe363c4ce
-  data.tar.gz: f255c179b502557624bfcfc81bc06743c13898bef9d7b5225e4519e097fbdfc7b88af2b2729088883747cb3a123f1a51fff521618527e68e7e77ca494212be32
+  metadata.gz: eb94613ee232272a8799ff0f7623c02d2d6e398ed0b7fbb231ff48bdf1e160ff99cb2110622567374012de4418e9b40129f7b14b0fabe7624904c399696f6dfc
+  data.tar.gz: 6327d0185659e82b95a922380cfbae030a42f91676a5a00d1a5fb43120c46eedd8d88432c0ec5cc7d20724494abd57be11ac6c47e2da26b536daa159174bf9ac

data/README.md

@@ -11,7 +11,7 @@ Choose where your flags live:
 | Backend | Use Case | Flags Stored In |
 |---------|----------|-----------------|
 | `:subflag` | Production with dashboard, environments, targeting | Subflag Cloud |
-| `:active_record` | Self-hosted, no external dependencies | Your database |
+| `:active_record` | Self-hosted, no external dependencies, [built-in admin UI](#admin-ui-activerecord) | Your database |
 | `:memory` | Testing and development | In-memory hash |
 
 **Same API regardless of backend:**
@@ -347,10 +347,11 @@ When using `backend: :active_record`, flags are stored in the `subflag_flags` ta
 | Column | Type | Description |
 |--------|------|-------------|
 | `key` | string | Flag name (lowercase, dashes, e.g., `new-checkout`) |
-| `value` | text | The flag value as a string |
+| `value` | text | Default value (what everyone gets) |
 | `value_type` | string | Type: `boolean`, `string`, `integer`, `float`, `object` |
 | `enabled` | boolean | Whether the flag is active (default: true) |
 | `description` | text | Optional description |
+| `targeting_rules` | json | Optional rules for showing different values to different users |
 
 ```ruby
 # Create flags
@@ -363,6 +364,150 @@ Subflag::Rails::Flag.enabled.find_each { |f| puts "#{f.key}: #{f.typed_value}" }
 Subflag::Rails::Flag.find_by(key: "new-checkout")&.update!(enabled: false)
 ```
 
+### Targeting Rules (ActiveRecord)
+
+Show different flag values to different users based on their attributes. Perfect for internal testing before wider rollout.
+
+> **Tip:** Use the [Admin UI](#admin-ui-activerecord) to manage targeting rules visually instead of editing JSON.
+
+**First, configure user context:**
+
+```ruby
+# config/initializers/subflag.rb
+Subflag::Rails.configure do |config|
+  config.backend = :active_record
+
+  config.user_context do |user|
+    {
+      targeting_key: user.id.to_s,
+      email: user.email,
+      role: user.role,           # e.g., "admin", "developer", "qa"
+      plan: user.plan            # e.g., "free", "pro", "enterprise"
+    }
+  end
+end
+```
+
+**Create flags with targeting rules:**
+
+```ruby
+# Internal team sees new feature, everyone else sees old
+Subflag::Rails::Flag.create!(
+  key: "new-dashboard",
+  value: "false",                    # Default: everyone gets false
+  value_type: "boolean",
+  targeting_rules: [
+    {
+      "value" => "true",             # Internal team gets true
+      "conditions" => {
+        "type" => "OR",
+        "conditions" => [
+          { "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@yourcompany.com" },
+          { "attribute" => "role", "operator" => "IN", "value" => ["admin", "developer", "qa"] }
+        ]
+      }
+    }
+  ]
+)
+```
+
+**Progressive rollout with multiple rules (first match wins):**
+
+```ruby
+Subflag::Rails::Flag.create!(
+  key: "max-projects",
+  value: "5",                        # Default: everyone gets 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" => "@yourcompany.com" }] } },
+    { "value" => "25", "conditions" => { "type" => "AND", "conditions" => [{ "attribute" => "plan", "operator" => "EQUALS", "value" => "pro" }] } }
+  ]
+)
+```
+
+**Supported operators:**
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| `EQUALS` | `{ "attribute" => "role", "operator" => "EQUALS", "value" => "admin" }` | Exact match |
+| `NOT_EQUALS` | `{ "attribute" => "env", "operator" => "NOT_EQUALS", "value" => "prod" }` | Not equal |
+| `IN` | `{ "attribute" => "role", "operator" => "IN", "value" => ["admin", "qa"] }` | Value in list |
+| `NOT_IN` | `{ "attribute" => "country", "operator" => "NOT_IN", "value" => ["RU", "CN"] }` | Value not in list |
+| `CONTAINS` | `{ "attribute" => "email", "operator" => "CONTAINS", "value" => "test" }` | String contains |
+| `NOT_CONTAINS` | `{ "attribute" => "email", "operator" => "NOT_CONTAINS", "value" => "spam" }` | String doesn't contain |
+| `STARTS_WITH` | `{ "attribute" => "user_id", "operator" => "STARTS_WITH", "value" => "test-" }` | String prefix |
+| `ENDS_WITH` | `{ "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@company.com" }` | String suffix |
+| `GREATER_THAN` | `{ "attribute" => "age", "operator" => "GREATER_THAN", "value" => 18 }` | Numeric greater than |
+| `LESS_THAN` | `{ "attribute" => "items", "operator" => "LESS_THAN", "value" => 100 }` | Numeric less than |
+| `GREATER_THAN_OR_EQUAL` | `{ "attribute" => "score", "operator" => "GREATER_THAN_OR_EQUAL", "value" => 80 }` | Numeric greater or equal |
+| `LESS_THAN_OR_EQUAL` | `{ "attribute" => "score", "operator" => "LESS_THAN_OR_EQUAL", "value" => 50 }` | Numeric less or equal |
+| `MATCHES` | `{ "attribute" => "email", "operator" => "MATCHES", "value" => ".*@company\\.com$" }` | Regex match |
+
+**Combining conditions:**
+
+```ruby
+# OR: any condition matches
+{
+  "type" => "OR",
+  "conditions" => [
+    { "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@company.com" },
+    { "attribute" => "role", "operator" => "EQUALS", "value" => "admin" }
+  ]
+}
+
+# AND: all conditions must match
+{
+  "type" => "AND",
+  "conditions" => [
+    { "attribute" => "plan", "operator" => "EQUALS", "value" => "enterprise" },
+    { "attribute" => "country", "operator" => "IN", "value" => ["US", "CA"] }
+  ]
+}
+```
+
+**How evaluation works:**
+
+1. Flag disabled? → return code default
+2. For each rule (in order): if context matches → return rule's value
+3. No rules matched? → return flag's default `value`
+
+This lets you progressively widen access by adding rules, without changing existing ones.
+
+### Admin UI (ActiveRecord)
+
+Mount the admin UI to manage flags and targeting rules visually:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount Subflag::Rails::Engine => "/subflag"
+  # ... your other routes
+end
+```
+
+The admin UI provides:
+- List, create, edit, and delete flags
+- Toggle flags enabled/disabled
+- Visual targeting rule builder (no JSON editing)
+- Test rules against sample contexts
+
+**Secure the admin UI:**
+
+```ruby
+# config/initializers/subflag.rb
+Subflag::Rails.configure do |config|
+  config.backend = :active_record
+
+  # Require authentication for admin UI
+  config.admin_auth do
+    redirect_to main_app.root_path unless current_user&.admin?
+  end
+end
+```
+
+Visit `/subflag` in your browser to access the admin UI.
+
 ## Testing
 
 Stub flags in your tests:

data/lib/generators/subflag/install_generator.rb

@@ -30,11 +30,19 @@ module Subflag
         end
       end
 
+      # Helper for templates to detect PostgreSQL adapter
+      def postgresql?
+        return false unless defined?(::ActiveRecord::Base)
+
+        adapter = ::ActiveRecord::Base.connection_db_config.adapter.to_s rescue nil
+        adapter&.include?("postgresql") || adapter&.include?("postgis")
+      end
+
       def create_initializer
         template "initializer.rb.tt", "config/initializers/subflag.rb"
       end
 
-      def create_migration
+      def create_flags_migration
         return unless options[:backend] == "active_record"
 
         migration_template "create_subflag_flags.rb.tt",

data/lib/generators/subflag/templates/create_subflag_flags.rb.tt

@@ -9,6 +9,11 @@ class CreateSubflagFlags < ActiveRecord::Migration[<%= ActiveRecord::Migration.c
       t.boolean :enabled, null: false, default: true
       t.text :description
 
+      # Targeting rules for showing different values to different users
+      # Stores an array of { value, conditions } rules as JSON
+      # First matching rule wins; falls back to `value` if no match
+      t.<%= postgresql? ? 'jsonb' : 'json' %> :targeting_rules
+
       t.timestamps
     end
 

data/lib/subflag/rails/backends/active_record_provider.rb

@@ -3,26 +3,32 @@
 module Subflag
   module Rails
     module Backends
-      # Provider that reads flags from your Rails database
+      # Provider that reads flags from your Rails database with targeting support.
       #
-      # Stores flags in a `subflag_flags` table with typed values.
-      # Perfect for teams who want self-hosted feature flags without external dependencies.
+      # Stores flags in a `subflag_flags` table with typed values and optional
+      # targeting rules for showing different values to different users.
       #
-      # @example
+      # @example Basic setup
       #   Subflag::Rails.configure do |config|
       #     config.backend = :active_record
       #   end
       #
-      #   # Create a flag
+      # @example Create a simple flag
       #   Subflag::Rails::Flag.create!(
       #     key: "max-projects",
       #     value: "100",
-      #     value_type: "integer",
-      #     enabled: true
+      #     value_type: "integer"
       #   )
       #
-      #   # Use it
-      #   subflag_value(:max_projects, default: 3)  # => 100
+      # @example Create a flag with targeting rules
+      #   Subflag::Rails::Flag.create!(
+      #     key: "new-dashboard",
+      #     value: "false",
+      #     value_type: "boolean",
+      #     targeting_rules: [
+      #       { "value" => "true", "conditions" => { "type" => "AND", "conditions" => [{ "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@company.com" }] } }
+      #     ]
+      #   )
       #
       class ActiveRecordProvider
         def metadata
@@ -33,40 +39,65 @@ module Subflag
         def shutdown; end
 
         def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
-          resolve(flag_key, default_value, :boolean)
+          resolve(flag_key, default_value, :boolean, evaluation_context)
         end
 
         def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
-          resolve(flag_key, default_value, :string)
+          resolve(flag_key, default_value, :string, evaluation_context)
         end
 
         def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
-          resolve(flag_key, default_value, :number)
+          resolve(flag_key, default_value, :number, evaluation_context)
         end
 
         def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
-          resolve(flag_key, default_value, :integer)
+          resolve(flag_key, default_value, :integer, evaluation_context)
         end
 
         def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
-          resolve(flag_key, default_value, :float)
+          resolve(flag_key, default_value, :float, evaluation_context)
         end
 
         def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
-          resolve(flag_key, default_value, :object)
+          resolve(flag_key, default_value, :object, evaluation_context)
         end
 
         private
 
-        def resolve(flag_key, default_value, expected_type)
+        def resolve(flag_key, default_value, expected_type, evaluation_context)
           flag = Subflag::Rails::Flag.find_by(key: flag_key)
 
           unless flag&.enabled?
             return resolution(default_value, reason: :default)
           end
 
-          value = flag.typed_value(expected_type)
-          resolution(value, reason: :static, variant: "default")
+          # Convert OpenFeature context to hash for targeting evaluation
+          context = context_to_hash(evaluation_context)
+          value = flag.evaluate(context: context, expected_type: expected_type)
+
+          # Determine if targeting matched
+          reason = flag.targeting_rules.present? && context.present? ? :targeting_match : :static
+          resolution(value, reason: reason, variant: "default")
+        end
+
+        def context_to_hash(evaluation_context)
+          return nil if evaluation_context.nil?
+
+          # OpenFeature::SDK::EvaluationContext stores fields as instance variables
+          # We need to extract them into a hash for our targeting engine
+          if evaluation_context.respond_to?(:to_h)
+            evaluation_context.to_h
+          elsif evaluation_context.respond_to?(:fields)
+            evaluation_context.fields
+          else
+            # Fallback: extract instance variables
+            hash = {}
+            evaluation_context.instance_variables.each do |var|
+              key = var.to_s.delete("@")
+              hash[key] = evaluation_context.instance_variable_get(var)
+            end
+            hash
+          end
         end
 
         def resolution(value, reason:, variant: nil)

data/lib/subflag/rails/configuration.rb

@@ -48,6 +48,9 @@ module Subflag
       #   Set to nil to disable cross-request caching (default).
       attr_accessor :cache_ttl
 
+      # @return [Proc, nil] Admin authentication callback for the admin UI
+      attr_reader :admin_auth_callback
+
       def initialize
         @backend = :subflag
         @api_key = nil
@@ -56,6 +59,7 @@ module Subflag
         @logging_enabled = false
         @log_level = :debug
         @cache_ttl = nil
+        @admin_auth_callback = nil
       end
 
       # Set the backend with validation
@@ -116,6 +120,25 @@ module Subflag
 
         @user_context_block.call(user)
       end
+
+      # Configure authentication for the admin UI
+      #
+      # @yield [controller] Block called before each admin action
+      # @yieldparam controller [ActionController::Base] The controller instance
+      #
+      # @example Require admin role
+      #   config.admin_auth do
+      #     redirect_to main_app.root_path unless current_user&.admin?
+      #   end
+      #
+      # @example Use Devise authenticate
+      #   config.admin_auth do
+      #     authenticate_user!
+      #   end
+      def admin_auth(&block)
+        @admin_auth_callback = block if block_given?
+        @admin_auth_callback
+      end
     end
   end
 end

data/lib/subflag/rails/engine.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # Mountable engine for the Subflag admin UI.
+    #
+    # Mount in your routes to get a web UI for managing flags:
+    #
+    #   # config/routes.rb
+    #   mount Subflag::Rails::Engine => "/subflag"
+    #
+    # The engine provides:
+    # - Flag CRUD (list, create, edit, delete)
+    # - Targeting rule builder
+    # - Rule testing interface
+    #
+    # Security: Configure authentication in an initializer:
+    #
+    #   Subflag::Rails.configure do |config|
+    #     config.admin_auth do |controller|
+    #       controller.authenticate_admin!  # Your auth method
+    #     end
+    #   end
+    #
+    class Engine < ::Rails::Engine
+      isolate_namespace Subflag::Rails
+
+      # Load engine routes
+      initializer "subflag.routes" do |app|
+        # Routes are loaded automatically from config/routes.rb
+      end
+    end
+  end
+end

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.0"
   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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: subflag-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Subflag
@@ -193,12 +193,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