subflag-rails 0.2.0 → 0.4.0

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,12 +2,47 @@
 
 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.
     # Most users should use `Subflag.flags` instead.
     #
     class Client
+      # Prefetch all flags for a user/context
+      #
+      # 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
+      # @return [Array<Hash>] Array of prefetched flag results (for inspection)
+      #
+      # @example
+      #   Subflag::Rails.client.prefetch_all(user: current_user)
+      #   # Subsequent lookups use cache - no API calls
+      #   subflag_enabled?(:new_feature)
+      #
+      def prefetch_all(user: nil, context: nil)
+        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
+      end
+
       # Check if a boolean flag is enabled
       #
       # @param flag_key [String] The flag key (already normalized)
@@ -17,6 +52,14 @@ module Subflag
       # @return [Boolean]
       def enabled?(flag_key, user: nil, context: nil, default: false)
         ctx = ContextBuilder.build(user: user, context: context)
+
+        # Check prefetch cache first
+        prefetched = get_prefetched_value(flag_key, ctx, :boolean)
+        if !prefetched.nil?
+          log_evaluation(flag_key, prefetched, default)
+          return prefetched
+        end
+
         cache_key = build_cache_key(flag_key, ctx, :boolean)
 
         result = RequestCache.fetch(cache_key) do
@@ -37,6 +80,15 @@ module Subflag
       # @raise [ArgumentError] If default is nil
       def value(flag_key, user: nil, context: nil, default:)
         ctx = ContextBuilder.build(user: user, context: context)
+
+        # Check prefetch cache first
+        expected_type = type_from_default(default)
+        prefetched = get_prefetched_value(flag_key, ctx, expected_type)
+        if !prefetched.nil?
+          log_evaluation(flag_key, prefetched, default)
+          return prefetched
+        end
+
         cache_key = build_cache_key(flag_key, ctx, default.class)
 
         result = RequestCache.fetch(cache_key) do
@@ -57,6 +109,14 @@ module Subflag
       # @raise [ArgumentError] If default is nil
       def evaluate(flag_key, user: nil, context: nil, default:)
         ctx = ContextBuilder.build(user: user, context: context)
+
+        # Check prefetch cache first - returns full EvaluationResult
+        prefetched_result = get_prefetched_result(flag_key, ctx)
+        if prefetched_result
+          log_evaluation(flag_key, prefetched_result.value, default)
+          return EvaluationResult.from_subflag(prefetched_result)
+        end
+
         cache_key = build_cache_key(flag_key, ctx, "details:#{default.class}")
 
         details = RequestCache.fetch(cache_key) do
@@ -69,6 +129,84 @@ 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)
+        results = subflag_client.evaluate_all(context: subflag_context)
+
+        # Cache each result in RequestCache for this request
+        results.each do |result|
+          cache_prefetched_result(result, context_hash)
+        end
+
+        results.map(&:to_h)
+      end
+
+      # Fetch flags using Rails.cache with TTL, falling back to API on cache miss
+      def prefetch_with_rails_cache(ctx, context_hash)
+        rails_cache_key = "subflag:all_flags:#{context_hash}"
+
+        cached_data = ::Rails.cache.fetch(rails_cache_key, expires_in: configuration.cache_ttl) do
+          # Cache miss - fetch from API
+          subflag_context = build_subflag_context(ctx)
+          results = subflag_client.evaluate_all(context: subflag_context)
+          results.map(&:to_h)
+        end
+
+        # Populate RequestCache from cached data (whether from Rails.cache or fresh fetch)
+        populate_request_cache_from_data(cached_data, context_hash)
+
+        cached_data
+      end
+
+      # Populate RequestCache from cached hash data (Subflag API)
+      def populate_request_cache_from_data(data_array, context_hash)
+        return unless RequestCache.enabled?
+
+        data_array.each do |result_hash|
+          result = ::Subflag::EvaluationResult.from_response(result_hash)
+          cache_prefetched_result(result, context_hash)
+        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}"
@@ -138,6 +276,81 @@ module Subflag
           logger.debug(message)
         end
       end
+
+      # Build Subflag::EvaluationContext from OpenFeature context
+      def build_subflag_context(openfeature_ctx)
+        return nil unless openfeature_ctx
+
+        ::Subflag::EvaluationContext.from_openfeature(openfeature_ctx)
+      end
+
+      # Get or create the Subflag HTTP client for direct API calls
+      def subflag_client
+        @subflag_client ||= ::Subflag::Client.new(
+          api_url: configuration.api_url,
+          api_key: configuration.api_key
+        )
+      end
+
+      # Cache a prefetched result for subsequent lookups
+      def cache_prefetched_result(result, context_hash)
+        # Store with a prefetch-specific key that includes the raw result
+        prefetch_key = "subflag:prefetch:#{result.flag_key}:#{context_hash}"
+        RequestCache.current_cache[prefetch_key] = result
+      end
+
+      # Check if a flag was prefetched and return its value
+      def get_prefetched_value(flag_key, ctx, expected_type)
+        return nil unless RequestCache.enabled?
+
+        context_hash = ctx ? ctx.hash : "no_context"
+        prefetch_key = "subflag:prefetch:#{flag_key}:#{context_hash}"
+        result = RequestCache.current_cache[prefetch_key]
+
+        return nil unless result
+
+        # Convert value to expected type if needed
+        convert_prefetched_value(result.value, expected_type)
+      end
+
+      # Get the full prefetched result for a flag (for evaluate method)
+      def get_prefetched_result(flag_key, ctx)
+        return nil unless RequestCache.enabled?
+
+        context_hash = ctx ? ctx.hash : "no_context"
+        prefetch_key = "subflag:prefetch:#{flag_key}:#{context_hash}"
+        RequestCache.current_cache[prefetch_key]
+      end
+
+      # Convert prefetched value to expected type
+      def convert_prefetched_value(value, expected_type)
+        case expected_type
+        when :boolean
+          value == true || value == false ? value : nil
+        when :string
+          value.is_a?(String) ? value : nil
+        when :integer
+          value.is_a?(Numeric) ? value.to_i : nil
+        when :float
+          value.is_a?(Numeric) ? value.to_f : nil
+        when :object
+          value.is_a?(Hash) ? value : nil
+        else
+          value
+        end
+      end
+
+      # Get expected type from default value
+      def type_from_default(default)
+        case default
+        when TrueClass, FalseClass then :boolean
+        when String then :string
+        when Integer then :integer
+        when Float then :float
+        when Hash then :object
+        else :unknown
+        end
+      end
     end
   end
 end

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
 
@@ -35,12 +43,42 @@ module Subflag
       # @return [Symbol] Log level for flag evaluations (:debug, :info, :warn)
       attr_accessor :log_level
 
+      # @return [Integer, ActiveSupport::Duration, nil] TTL for cross-request caching
+      #   When set, prefetched flags are cached in Rails.cache for this duration.
+      #   Set to nil to disable cross-request caching (default).
+      attr_accessor :cache_ttl
+
       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
+      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
+      #
+      # @return [Boolean]
+      def rails_cache_enabled?
+        return false unless @cache_ttl && @cache_ttl.to_i > 0
+        return false unless defined?(::Rails.cache) && ::Rails.cache.present?
+
+        true
       end
 
       # Configure how to extract context from a user object

data/lib/subflag/rails/evaluation_result.rb

@@ -92,6 +92,22 @@ module Subflag
           error_message: details[:error_message]
         )
       end
+
+      # Build from Subflag::EvaluationResult (from Ruby provider)
+      #
+      # @param result [Subflag::EvaluationResult] The provider's evaluation result
+      # @return [EvaluationResult]
+      def self.from_subflag(result)
+        # Convert uppercase reason string to lowercase symbol
+        reason = result.reason&.downcase&.to_sym || :unknown
+
+        new(
+          value: result.value,
+          variant: result.variant,
+          reason: reason,
+          flag_key: result.flag_key
+        )
+      end
     end
   end
 end

data/lib/subflag/rails/helpers.rb

@@ -93,6 +93,36 @@ module Subflag
         Subflag.flags(user: resolved, context: context)
       end
 
+      # Prefetch all flags for a user in a single API call
+      #
+      # Call this early in a request (e.g., in a before_action) to fetch
+      # all flags at once. Subsequent flag lookups will use the cached values.
+      #
+      # Automatically scoped to current_user if available.
+      #
+      # @param user [Object, nil, :auto] User for targeting (default: current_user)
+      # @param context [Hash, nil] Additional context attributes
+      # @return [Array<Hash>] Array of prefetched flag results (for inspection)
+      #
+      # @example In ApplicationController
+      #   class ApplicationController < ActionController::Base
+      #     before_action :prefetch_feature_flags
+      #
+      #     private
+      #
+      #     def prefetch_feature_flags
+      #       subflag_prefetch  # Uses current_user automatically
+      #     end
+      #   end
+      #
+      # @example Without user context
+      #   subflag_prefetch(nil)
+      #
+      def subflag_prefetch(user = :auto, context: nil)
+        resolved = resolve_user(user)
+        Subflag.prefetch_flags(user: resolved, context: context)
+      end
+
       private
 
       # Resolve user parameter - use current_user if :auto and available

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # ActiveRecord model for storing feature flags in your database
+    #
+    # @example Create a boolean flag
+    #   Subflag::Rails::Flag.create!(
+    #     key: "new-checkout",
+    #     value: "true",
+    #     value_type: "boolean"
+    #   )
+    #
+    # @example Create an integer flag
+    #   Subflag::Rails::Flag.create!(
+    #     key: "max-projects",
+    #     value: "100",
+    #     value_type: "integer"
+    #   )
+    #
+    # @example Create a JSON object flag
+    #   Subflag::Rails::Flag.create!(
+    #     key: "feature-limits",
+    #     value: '{"max_items": 10, "max_users": 5}',
+    #     value_type: "object"
+    #   )
+    #
+    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
+
+      scope :enabled, -> { where(enabled: true) }
+
+      # Get the flag value cast to its declared type
+      #
+      # @param expected_type [Symbol, String, nil] Override the value_type for casting
+      # @return [Object] The typed value
+      def typed_value(expected_type = nil)
+        type = expected_type&.to_s || value_type
+
+        case type.to_s
+        when "boolean"
+          ActiveModel::Type::Boolean.new.cast(value)
+        when "string"
+          value.to_s
+        when "integer"
+          value.to_i
+        when "float", "number"
+          value.to_f
+        when "object"
+          value.is_a?(Hash) ? value : JSON.parse(value)
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/subflag/rails/version.rb

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