subflag-rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b994b3be254b327ab4c2d7f94ed4a30a9af6a47af2c19b58089b02b5d8487e5
-  data.tar.gz: 267fb6f5df4a770f7133ee475ae364118bc2459031137434160cf17ddf91033c
+  metadata.gz: 2d5585ee53dcf0c1864f3d9bf5845a41cd8e3c884fe11ca457bc51b3ded8cfcd
+  data.tar.gz: 1014353a80ee041027dd501aea4035f7043b873dbf75506678e2852b948f436a
 SHA512:
-  metadata.gz: bda7f1465a5f3eabf2baa0190c372c4687b731ad5cb43a9d11851b78b9d23457c9dbdffb65f2235f92f61b18841ed1bddc8d5b6eae27d89ac4b9802db6b81df3
-  data.tar.gz: 950362e174920f95c08309a8cfc406e1249612f554f0cd51df13f580c8f6a73492cca56e2ff597dcba94fbb6914d66e069569a23c5df0c139ded9c7983561860
+  metadata.gz: 7a0b5adb5b8df94ed4e07ba41e47b4430b719b2cf741695b6f9029239aefa6437535d36fb08d9b2f12d84911126cdfa45d15429b2c024f0d93c694f6ee5e77e8
+  data.tar.gz: 582032e633830bb9e5867ae6883545a4ba5fd0ece16556a542f9de3513a5c0853f4ce7a121ad4af3d3ea6bc901ff136abc9f77f12eaa37789d64fa77bd11a750

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.0] - 2025-12-07
+
+### Added
+
+- **Bulk flag evaluation**: `subflag_prefetch` helper fetches all flags in a single API call
+- **Cross-request caching**: `config.cache_ttl` enables caching via `Rails.cache` with configurable TTL
+- `Subflag.prefetch_flags` and `Subflag::Rails.prefetch_flags` module methods
+
+### Changed
+
+- Requires `subflag-openfeature-provider` >= 0.3.1
+
 ## [0.2.0] - 2025-11-30
 
 ### Changed

data/README.md

@@ -214,6 +214,84 @@ subflag_enabled?(:new_checkout)  # Cache hit
 subflag_enabled?(:new_checkout)  # Cache hit
 ```
 
+## Bulk Flag Evaluation (Prefetch)
+
+For optimal performance, prefetch all flags for a user in a single API call. This is especially useful when your page checks multiple flags:
+
+```ruby
+# config/application.rb (required)
+config.middleware.use Subflag::Rails::RequestCache::Middleware
+```
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :prefetch_feature_flags
+
+  private
+
+  def prefetch_feature_flags
+    subflag_prefetch  # Fetches all flags for current_user in one API call
+  end
+end
+```
+
+Now all subsequent flag lookups use the cache — no additional API calls:
+
+```ruby
+# In your controller/view - all lookups are instant (cache hits)
+subflag_enabled?(:new_checkout)           # Cache hit
+subflag_value(:max_projects, default: 3)  # Cache hit
+subflag_value(:headline, default: "Hi")   # Cache hit
+```
+
+### How It Works
+
+1. **Single API call**: `subflag_prefetch` calls `/sdk/evaluate-all` to fetch all flags
+2. **Per-request cache**: Results are stored in `RequestCache` for the duration of the request
+3. **Zero-latency lookups**: Subsequent `subflag_enabled?` and `subflag_value` calls read from cache
+
+### Prefetch Without current_user
+
+```ruby
+# No user context
+subflag_prefetch(nil)
+
+# With specific user
+subflag_prefetch(admin_user)
+
+# With additional context
+subflag_prefetch(current_user, context: { device: "mobile" })
+```
+
+### Cross-Request Caching
+
+By default, prefetched flags are only cached for the current request. To cache across multiple requests using `Rails.cache`, set a TTL:
+
+```ruby
+# config/initializers/subflag.rb
+Subflag::Rails.configure do |config|
+  config.api_key = Rails.application.credentials.subflag_api_key
+  config.cache_ttl = 30.seconds  # Cache flags in Rails.cache for 30 seconds
+end
+```
+
+With `cache_ttl` set:
+- First request fetches from API and stores in `Rails.cache`
+- Subsequent requests (within TTL) read from `Rails.cache` — no API call
+- After TTL expires, next request fetches fresh data
+
+This significantly reduces API load for high-traffic applications. Choose a TTL that balances freshness with performance — 30 seconds is a good starting point.
+
+### Direct API
+
+You can also use the module method directly:
+
+```ruby
+Subflag.prefetch_flags(user: current_user)
+# or
+Subflag::Rails.prefetch_flags(user: current_user)
+```
+
 ## Configuration
 
 ```ruby
@@ -224,6 +302,10 @@ Subflag::Rails.configure do |config|
   # API URL (default: https://api.subflag.com)
   config.api_url = "https://api.subflag.com"
 
+  # Cross-request caching via Rails.cache (optional)
+  # When set, prefetched flags are cached for this duration
+  config.cache_ttl = 30.seconds
+
   # Logging
   config.logging_enabled = Rails.env.development?
   config.log_level = :debug  # :debug, :info, :warn

data/lib/subflag/rails/client.rb

@@ -8,6 +8,33 @@ module Subflag
     # Most users should use `Subflag.flags` instead.
     #
     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.
+      #
+      # @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)
+        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
+
       # Check if a boolean flag is enabled
       #
       # @param flag_key [String] The flag key (already normalized)
@@ -17,6 +44,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 +72,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 +101,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 +121,46 @@ module Subflag
 
       private
 
+      # 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
+      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
+
       def build_cache_key(flag_key, ctx, type)
         context_hash = ctx ? ctx.hash : "no_context"
         "subflag:#{flag_key}:#{context_hash}:#{type}"
@@ -138,6 +230,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

@@ -35,12 +35,28 @@ 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
         @api_key = nil
         @api_url = "https://api.subflag.com"
         @user_context_block = nil
         @logging_enabled = false
         @log_level = :debug
+        @cache_ttl = nil
+      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/version.rb

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

data/lib/subflag/rails.rb

@@ -48,6 +48,26 @@ module Subflag
         @client ||= Client.new
       end
 
+      # Prefetch all flags for a user/context in a single API call
+      #
+      # Call this early in a request to fetch all flags at once.
+      # Subsequent flag lookups will use the cached values.
+      #
+      # @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 Prefetch in a controller
+      #   before_action :prefetch_flags
+      #
+      #   def prefetch_flags
+      #     Subflag::Rails.prefetch_flags(user: current_user)
+      #   end
+      #
+      def prefetch_flags(user: nil, context: nil)
+        client.prefetch_all(user: user, context: context)
+      end
+
       # Reset configuration (primarily for testing)
       def reset!
         @configuration = Configuration.new
@@ -92,5 +112,20 @@ module Subflag
     def flags(user: nil, context: nil)
       Rails::FlagAccessor.new(user: user, context: context)
     end
+
+    # Prefetch all flags for a user/context in a single API call
+    #
+    # @param user [Object, nil] The user object for targeting
+    # @param context [Hash, nil] Additional context attributes
+    # @return [Array<Hash>] Array of prefetched flag results
+    #
+    # @example
+    #   Subflag.prefetch_flags(user: current_user)
+    #   # Subsequent lookups use cache
+    #   Subflag.flags(user: current_user).new_feature?(default: false)
+    #
+    def prefetch_flags(user: nil, context: nil)
+      Rails.prefetch_flags(user: user, context: context)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: subflag-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Subflag
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-01 00:00:00.000000000 Z
+date: 2025-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: subflag-openfeature-provider
@@ -16,7 +16,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.3.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.0'
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.3.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.0'