subflag-rails 0.3.0 → 0.5.0

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    module Backends
+      # Provider that reads flags from your Rails database with targeting support.
+      #
+      # Stores flags in a `subflag_flags` table with typed values and optional
+      # targeting rules for showing different values to different users.
+      #
+      # @example Basic setup
+      #   Subflag::Rails.configure do |config|
+      #     config.backend = :active_record
+      #   end
+      #
+      # @example Create a simple flag
+      #   Subflag::Rails::Flag.create!(
+      #     key: "max-projects",
+      #     value: "100",
+      #     value_type: "integer"
+      #   )
+      #
+      # @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
+          { name: "Subflag ActiveRecord Provider" }
+        end
+
+        def init; end
+        def shutdown; end
+
+        def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+          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, evaluation_context)
+        end
+
+        def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+          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, evaluation_context)
+        end
+
+        def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+          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, evaluation_context)
+        end
+
+        private
+
+        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
+
+          # 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)
+          OpenFeature::SDK::Provider::ResolutionDetails.new(
+            value: value,
+            reason: reason,
+            variant: variant
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    module Backends
+      # In-memory provider for testing and development
+      #
+      # Flags are stored in a hash and reset when the process restarts.
+      # Useful for unit tests and local development without external dependencies.
+      #
+      # @example In tests
+      #   Subflag::Rails.configure do |config|
+      #     config.backend = :memory
+      #   end
+      #
+      #   # Set flags directly
+      #   Subflag::Rails.provider.set(:new_checkout, true)
+      #   Subflag::Rails.provider.set(:max_projects, 100)
+      #
+      #   # Use them
+      #   subflag_enabled?(:new_checkout)  # => true
+      #
+      class MemoryProvider
+        def initialize
+          @flags = {}
+        end
+
+        def metadata
+          { name: "Subflag Memory Provider" }
+        end
+
+        def init; end
+        def shutdown; end
+
+        # Set a flag value programmatically
+        #
+        # @param key [String, Symbol] The flag key (underscores converted to dashes)
+        # @param value [Object] The flag value
+        # @param enabled [Boolean] Whether the flag is enabled (default: true)
+        def set(key, value, enabled: true)
+          @flags[normalize_key(key)] = { value: value, enabled: enabled }
+        end
+
+        # Clear all flags
+        def clear
+          @flags.clear
+        end
+
+        # Get all flags (for debugging)
+        def all
+          @flags.dup
+        end
+
+        def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+          resolve(flag_key, default_value)
+        end
+
+        def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+          resolve(flag_key, default_value)
+        end
+
+        def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+          resolve(flag_key, default_value)
+        end
+
+        def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+          resolve(flag_key, default_value)
+        end
+
+        def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+          resolve(flag_key, default_value)
+        end
+
+        def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+          resolve(flag_key, default_value)
+        end
+
+        private
+
+        def normalize_key(key)
+          key.to_s.tr("_", "-")
+        end
+
+        def resolve(flag_key, default_value)
+          flag = @flags[flag_key.to_s]
+
+          unless flag && flag[:enabled]
+            return resolution(default_value, reason: :default)
+          end
+
+          resolution(flag[:value], reason: :static, variant: "default")
+        end
+
+        def resolution(value, reason:, variant: nil)
+          OpenFeature::SDK::Provider::ResolutionDetails.new(
+            value: value,
+            reason: reason,
+            variant: variant
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    module Backends
+      # Provider wrapper for Subflag Cloud SaaS
+      #
+      # Delegates to the standalone subflag-openfeature-provider gem.
+      # This is the default backend when using Subflag::Rails.
+      #
+      # @example
+      #   Subflag::Rails.configure do |config|
+      #     config.backend = :subflag
+      #     config.api_key = "sdk-production-..."
+      #   end
+      #
+      class SubflagProvider
+        def initialize(api_key:, api_url:)
+          require "subflag"
+          @provider = ::Subflag::Provider.new(api_key: api_key, api_url: api_url)
+        end
+
+        def metadata
+          @provider.metadata
+        end
+
+        def init
+          @provider.init
+        end
+
+        def shutdown
+          @provider.shutdown
+        end
+
+        def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+          @provider.fetch_boolean_value(
+            flag_key: flag_key,
+            default_value: default_value,
+            evaluation_context: evaluation_context
+          )
+        end
+
+        def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+          @provider.fetch_string_value(
+            flag_key: flag_key,
+            default_value: default_value,
+            evaluation_context: evaluation_context
+          )
+        end
+
+        def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+          @provider.fetch_number_value(
+            flag_key: flag_key,
+            default_value: default_value,
+            evaluation_context: evaluation_context
+          )
+        end
+
+        def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+          @provider.fetch_integer_value(
+            flag_key: flag_key,
+            default_value: default_value,
+            evaluation_context: evaluation_context
+          )
+        end
+
+        def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+          @provider.fetch_float_value(
+            flag_key: flag_key,
+            default_value: default_value,
+            evaluation_context: evaluation_context
+          )
+        end
+
+        def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+          @provider.fetch_object_value(
+            flag_key: flag_key,
+            default_value: default_value,
+            evaluation_context: evaluation_context
+          )
+        end
+      end
+    end
+  end
+end

data/lib/subflag/rails/client.rb

@@ -2,6 +2,10 @@
 
 module Subflag
   module Rails
+    # Lightweight struct for caching prefetched flag results
+    # Used by ActiveRecord and Memory backends where we don't have Subflag::EvaluationResult
+    PrefetchedFlag = Struct.new(:flag_key, :value, :reason, :variant, keyword_init: true)
+
     # Client for evaluating feature flags
     #
     # This is the low-level client used by FlagAccessor.
@@ -10,8 +14,11 @@ module Subflag
     class Client
       # Prefetch all flags for a user/context
       #
-      # Fetches all flags in a single API call and caches them.
-      # Subsequent flag lookups will use the cached values.
+      # Fetches all flags and caches them for subsequent lookups.
+      # Behavior varies by backend:
+      # - :subflag — Single API call to fetch all flags
+      # - :active_record — Single DB query to load all enabled flags
+      # - :memory — No-op (flags already in memory)
       #
       # @param user [Object, nil] The user object for targeting
       # @param context [Hash, nil] Additional context attributes
@@ -23,16 +30,17 @@ module Subflag
       #   subflag_enabled?(:new_feature)
       #
       def prefetch_all(user: nil, context: nil)
-        ctx = ContextBuilder.build(user: user, context: context)
-        context_hash = ctx ? ctx.hash : "no_context"
-
-        # Use Rails.cache for cross-request caching if enabled
-        if configuration.rails_cache_enabled?
-          return prefetch_with_rails_cache(ctx, context_hash)
+        case configuration.backend
+        when :subflag
+          prefetch_from_subflag_api(user: user, context: context)
+        when :active_record
+          prefetch_from_active_record(user: user, context: context)
+        when :memory
+          # Already in memory, nothing to prefetch
+          []
+        else
+          []
         end
-
-        # Otherwise fetch directly from API (per-request cache only)
-        prefetch_from_api(ctx, context_hash)
       end
 
       # Check if a boolean flag is enabled
@@ -121,6 +129,20 @@ module Subflag
 
       private
 
+      # Prefetch flags from Subflag Cloud API
+      def prefetch_from_subflag_api(user:, context:)
+        ctx = ContextBuilder.build(user: user, context: context)
+        context_hash = ctx ? ctx.hash : "no_context"
+
+        # Use Rails.cache for cross-request caching if enabled
+        if configuration.rails_cache_enabled?
+          return prefetch_with_rails_cache(ctx, context_hash)
+        end
+
+        # Otherwise fetch directly from API (per-request cache only)
+        prefetch_from_api(ctx, context_hash)
+      end
+
       # Fetch flags from API and populate RequestCache
       def prefetch_from_api(ctx, context_hash)
         subflag_context = build_subflag_context(ctx)
@@ -151,7 +173,7 @@ module Subflag
         cached_data
       end
 
-      # Populate RequestCache from cached hash data
+      # Populate RequestCache from cached hash data (Subflag API)
       def populate_request_cache_from_data(data_array, context_hash)
         return unless RequestCache.enabled?
 
@@ -161,6 +183,30 @@ module Subflag
         end
       end
 
+      # Prefetch flags from ActiveRecord database
+      # Loads all enabled flags in one query and caches their values
+      def prefetch_from_active_record(user:, context:)
+        return [] unless RequestCache.enabled?
+
+        ctx = ContextBuilder.build(user: user, context: context)
+        context_hash = ctx ? ctx.hash : "no_context"
+
+        prefetched = []
+
+        Subflag::Rails::Flag.enabled.find_each do |flag|
+          prefetch_key = "subflag:prefetch:#{flag.key}:#{context_hash}"
+          RequestCache.current_cache[prefetch_key] = PrefetchedFlag.new(
+            flag_key: flag.key,
+            value: flag.typed_value,
+            reason: "STATIC",
+            variant: "default"
+          )
+          prefetched << { flag_key: flag.key, value: flag.typed_value }
+        end
+
+        prefetched
+      end
+
       def build_cache_key(flag_key, ctx, type)
         context_hash = ctx ? ctx.hash : "no_context"
         "subflag:#{flag_key}:#{context_hash}:#{type}"

data/lib/subflag/rails/configuration.rb

@@ -23,6 +23,14 @@ module Subflag
     #   end
     #
     class Configuration
+      VALID_BACKENDS = %i[subflag active_record memory].freeze
+
+      # @return [Symbol] Backend to use (:subflag, :active_record, :memory)
+      #   - :subflag — Subflag Cloud SaaS (default)
+      #   - :active_record — Self-hosted, flags stored in your database
+      #   - :memory — In-memory store for testing
+      attr_reader :backend
+
       # @return [String, nil] The Subflag API key
       attr_accessor :api_key
 
@@ -40,13 +48,31 @@ 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
         @api_url = "https://api.subflag.com"
         @user_context_block = nil
         @logging_enabled = false
         @log_level = :debug
         @cache_ttl = nil
+        @admin_auth_callback = nil
+      end
+
+      # Set the backend with validation
+      #
+      # @param value [Symbol] The backend to use
+      # @raise [ArgumentError] If the backend is invalid
+      def backend=(value)
+        value = value.to_sym
+        unless VALID_BACKENDS.include?(value)
+          raise ArgumentError, "Invalid backend: #{value}. Use one of: #{VALID_BACKENDS.join(', ')}"
+        end
+
+        @backend = value
       end
 
       # Check if cross-request caching via Rails.cache is enabled
@@ -94,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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # ActiveRecord model for storing feature flags in your database.
+    #
+    # 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 Flag with targeting rules (internal team gets different value)
+    #   Subflag::Rails::Flag.create!(
+    #     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 Progressive rollout (first match wins)
+    #   Subflag::Rails::Flag.create!(
+    #     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
+      self.table_name = "subflag_flags"
+
+      VALUE_TYPES = %w[boolean string integer float object].freeze
+
+      validates :key, presence: true,
+                      uniqueness: true,
+                      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) }
+
+      # 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(raw_value)
+        when "string"
+          raw_value.to_s
+        when "integer"
+          raw_value.to_i
+        when "float", "number"
+          raw_value.to_f
+        when "object"
+          raw_value.is_a?(Hash) ? raw_value : JSON.parse(raw_value)
+        else
+          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
+  end
+end