subflag-rails 0.1.0

data/lib/subflag/rails/evaluation_result.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # Result of a flag evaluation with full details
+    #
+    # @example
+    #   result = Subflag.flags(user: current_user).evaluate(:max_projects, default: 3)
+    #   result.value       # => 100
+    #   result.variant     # => "premium"
+    #   result.reason      # => :targeting_match
+    #   result.flag_key    # => "max-projects"
+    #   result.default?    # => false
+    #   result.error?      # => false
+    #
+    class EvaluationResult
+      # @return [Object] The resolved flag value
+      attr_reader :value
+
+      # @return [String, nil] The variant name that was selected
+      attr_reader :variant
+
+      # @return [Symbol] The reason for this evaluation result
+      #   Possible values: :default, :targeting_match, :static, :split, :error, :unknown
+      attr_reader :reason
+
+      # @return [String] The flag key that was evaluated
+      attr_reader :flag_key
+
+      # @return [Symbol, nil] Error code if evaluation failed
+      attr_reader :error_code
+
+      # @return [String, nil] Error message if evaluation failed
+      attr_reader :error_message
+
+      def initialize(value:, variant: nil, reason: :unknown, flag_key:, error_code: nil, error_message: nil)
+        @value = value
+        @variant = variant
+        @reason = reason
+        @flag_key = flag_key
+        @error_code = error_code
+        @error_message = error_message
+      end
+
+      # Check if the default value was returned
+      #
+      # @return [Boolean]
+      def default?
+        reason == :default
+      end
+
+      # Check if there was an error during evaluation
+      #
+      # @return [Boolean]
+      def error?
+        reason == :error || !error_code.nil?
+      end
+
+      # Check if the value came from targeting rules
+      #
+      # @return [Boolean]
+      def targeted?
+        reason == :targeting_match
+      end
+
+      # Convert to hash representation
+      #
+      # @return [Hash]
+      def to_h
+        {
+          value: value,
+          variant: variant,
+          reason: reason,
+          flag_key: flag_key,
+          error_code: error_code,
+          error_message: error_message
+        }.compact
+      end
+
+      # Build from OpenFeature evaluation details
+      #
+      # @param details [Hash] OpenFeature evaluation details hash
+      # @param flag_key [String] The flag key
+      # @return [EvaluationResult]
+      def self.from_openfeature(details, flag_key:)
+        new(
+          value: details[:value],
+          variant: details[:variant],
+          reason: details[:reason] || :unknown,
+          flag_key: flag_key,
+          error_code: details[:error_code],
+          error_message: details[:error_message]
+        )
+      end
+    end
+  end
+end

data/lib/subflag/rails/flag_accessor.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # Dynamic flag accessor using method_missing
+    #
+    # Provides a clean DSL for accessing flags:
+    #
+    # @example Boolean flags (? suffix) - default is optional (false)
+    #   Subflag.flags.new_checkout?
+    #   Subflag.flags.new_checkout?(default: true)
+    #
+    # @example Value flags - default is REQUIRED
+    #   Subflag.flags.homepage_headline(default: "Welcome")
+    #   Subflag.flags.max_projects(default: 3)
+    #   Subflag.flags.tax_rate(default: 0.08)
+    #   Subflag.flags.feature_limits(default: {})
+    #
+    # @example With user context
+    #   Subflag.flags(user: current_user).max_projects(default: 3)
+    #
+    # @example Bracket access (exact flag names, default required)
+    #   Subflag.flags["my-exact-flag", default: "value"]
+    #
+    # @example Full evaluation details
+    #   result = Subflag.flags.evaluate(:max_projects, default: 3)
+    #   result.value    # => 100
+    #   result.reason   # => :targeting_match
+    #
+    # Flag names are automatically converted:
+    # - Underscores become dashes: `new_checkout` → `new-checkout`
+    # - Trailing ? is removed for booleans: `enabled?` → `enabled`
+    #
+    class FlagAccessor
+      def initialize(user: nil, context: nil)
+        @user = user
+        @context = context
+      end
+
+      # Bracket access for exact flag names (no conversion)
+      #
+      # @param flag_name [String, Symbol] The exact flag name
+      # @param default [Object] Default value (required)
+      # @return [Object] The flag value
+      # @raise [ArgumentError] If default is not provided
+      #
+      # @example
+      #   Subflag.flags["my-exact-flag", default: "value"]
+      #
+      def [](flag_name, default:)
+        flag_key = flag_name.to_s
+        client.value(flag_key, user: @user, context: @context, default: default)
+      end
+
+      # Get full evaluation details for a flag
+      #
+      # @param flag_name [String, Symbol] The flag name
+      # @param default [Object] Default value (required)
+      # @return [EvaluationResult] Full evaluation result
+      # @raise [ArgumentError] If default is not provided
+      #
+      # @example
+      #   result = Subflag.flags.evaluate(:max_projects, default: 3)
+      #   result.value    # => 100
+      #   result.variant  # => "premium"
+      #   result.reason   # => :targeting_match
+      #
+      def evaluate(flag_name, default:)
+        flag_key = normalize_flag_name(flag_name)
+        client.evaluate(flag_key, user: @user, context: @context, default: default)
+      end
+
+      # Handle dynamic flag access
+      #
+      # Method names ending in ? are treated as boolean flags (default: false).
+      # All other methods require a default: keyword argument.
+      #
+      # @example Boolean (default optional)
+      #   flags.new_checkout?              # default: false
+      #   flags.new_checkout?(default: true)
+      #
+      # @example Value (default required)
+      #   flags.max_projects(default: 3)
+      #   flags.headline(default: "Hi")
+      #
+      def method_missing(method_name, *args, **kwargs, &block)
+        flag_key = normalize_flag_name(method_name)
+
+        if method_name.to_s.end_with?("?")
+          # Boolean flag - default is optional (false)
+          default = kwargs.fetch(:default, false)
+          client.enabled?(flag_key, user: @user, context: @context, default: default)
+        else
+          # Value flag - default is required
+          unless kwargs.key?(:default)
+            raise ArgumentError, "default is required: Subflag.flags.#{method_name}(default: <value>)"
+          end
+          client.value(flag_key, user: @user, context: @context, default: kwargs[:default])
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        true
+      end
+
+      private
+
+      def client
+        Subflag::Rails.client
+      end
+
+      # Convert Ruby method name to flag key
+      #
+      # - Removes trailing ? for boolean methods
+      # - Converts underscores to dashes
+      #
+      # @param method_name [Symbol, String] The method/flag name
+      # @return [String] The normalized flag key
+      #
+      # @example
+      #   normalize_flag_name(:new_checkout?)  # => "new-checkout"
+      #   normalize_flag_name(:max_projects)   # => "max-projects"
+      #
+      def normalize_flag_name(method_name)
+        method_name.to_s.chomp("?").tr("_", "-")
+      end
+    end
+  end
+end

data/lib/subflag/rails/helpers.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # Helpers for using Subflag in controllers and views
+    #
+    # All helpers automatically use `current_user` for targeting if available.
+    # Override with `user: nil` or `user: other_user` when needed.
+    #
+    # @example Controller
+    #   class ProjectsController < ApplicationController
+    #     def index
+    #       if subflag_enabled?(:new_dashboard)
+    #         # show new dashboard
+    #       end
+    #       @max_projects = subflag_value(:max_projects, default: 3)
+    #     end
+    #   end
+    #
+    # @example View
+    #   <% if subflag_enabled?(:new_checkout) %>
+    #     <%= render "new_checkout" %>
+    #   <% end %>
+    #   <h1><%= subflag_value(:headline, default: "Welcome") %></h1>
+    #
+    # @example Flag accessor for multiple checks
+    #   flags = subflag_for
+    #   if flags.beta_feature?
+    #     max = flags.max_projects(default: 3)
+    #   end
+    #
+    module Helpers
+      # Check if a boolean flag is enabled
+      #
+      # Automatically scoped to current_user if available.
+      #
+      # @param flag_name [Symbol, String] The flag name (underscores → dashes)
+      # @param user [Object, nil, :auto] User for targeting (default: current_user)
+      # @param context [Hash, nil] Additional context attributes
+      # @param default [Boolean] Default value (optional, defaults to false)
+      # @return [Boolean]
+      #
+      # @example
+      #   <% if subflag_enabled?(:new_checkout) %>
+      #   <% if subflag_enabled?(:admin_feature, user: nil) %>  <!-- no user context -->
+      #
+      def subflag_enabled?(flag_name, user: :auto, context: nil, default: false)
+        resolved = resolve_user(user)
+        Subflag.flags(user: resolved, context: context).public_send(:"#{flag_name}?", default: default)
+      end
+
+      # Get a flag value (default required)
+      #
+      # Automatically scoped to current_user if available.
+      #
+      # @param flag_name [Symbol, String] The flag name (underscores → dashes)
+      # @param default [Object] Default value (required - determines type)
+      # @param user [Object, nil, :auto] User for targeting (default: current_user)
+      # @param context [Hash, nil] Additional context attributes
+      # @return [Object] The flag value
+      #
+      # @example
+      #   <%= subflag_value(:headline, default: "Welcome") %>
+      #   <%= subflag_value(:max_items, user: nil, default: 10) %>
+      #
+      def subflag_value(flag_name, default:, user: :auto, context: nil)
+        resolved = resolve_user(user)
+        Subflag.flags(user: resolved, context: context).public_send(flag_name, default: default)
+      end
+
+      # Get a flag accessor, optionally for a specific user
+      #
+      # Automatically scoped to current_user if no user provided.
+      #
+      # @param user [Object, nil, :auto] User for targeting (default: current_user)
+      # @param context [Hash, nil] Additional context attributes
+      # @return [FlagAccessor] A flag accessor
+      #
+      # @example Using current_user automatically
+      #   <% flags = subflag_for %>
+      #   <% if flags.beta_feature? %>
+      #     <h1><%= flags.welcome_message(default: "Hello!") %></h1>
+      #   <% end %>
+      #
+      # @example Without user context
+      #   <% flags = subflag_for(nil) %>
+      #
+      # @example With specific user
+      #   <% flags = subflag_for(admin_user) %>
+      #
+      def subflag_for(user = :auto, context: nil)
+        resolved = resolve_user(user)
+        Subflag.flags(user: resolved, context: context)
+      end
+
+      private
+
+      # Resolve user parameter - use current_user if :auto and available
+      #
+      # @param user [Object, nil, :auto]
+      # @return [Object, nil]
+      def resolve_user(user)
+        return user unless user == :auto
+        respond_to?(:current_user, true) ? current_user : nil
+      end
+    end
+  end
+end

data/lib/subflag/rails/railtie.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # Railtie for automatic Rails integration
+    #
+    # This handles:
+    # - Registering helpers in views AND controllers
+    # - Auto-configuring from credentials if available
+    #
+    class Railtie < ::Rails::Railtie
+      # Include helpers in views and controllers
+      initializer "subflag.helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include Subflag::Rails::Helpers
+        end
+
+        ActiveSupport.on_load(:action_controller_base) do
+          include Subflag::Rails::Helpers
+        end
+
+        ActiveSupport.on_load(:action_controller_api) do
+          include Subflag::Rails::Helpers
+        end
+      end
+
+      # Auto-configure from credentials
+      initializer "subflag.configure" do
+        config.after_initialize do
+          next if Subflag::Rails.configuration.api_key
+
+          api_key = ::Rails.application.credentials.dig(:subflag, :api_key) ||
+                    ::Rails.application.credentials.subflag_api_key ||
+                    ENV["SUBFLAG_API_KEY"]
+
+          if api_key
+            Subflag::Rails.configure do |c|
+              c.api_key = api_key
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/subflag/rails/request_cache.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # Per-request cache for flag evaluations
+    #
+    # Caches flag values for the duration of a single request to avoid
+    # multiple API calls for the same flag.
+    #
+    # @example Enable in application.rb
+    #   # config/application.rb
+    #   config.middleware.use Subflag::Rails::RequestCache::Middleware
+    #
+    # @example Or in initializer
+    #   # config/initializers/subflag.rb
+    #   Rails.application.config.middleware.use Subflag::Rails::RequestCache::Middleware
+    #
+    module RequestCache
+      class << self
+        # Get a cached value or yield to fetch it
+        #
+        # @param cache_key [String] Unique key for this evaluation
+        # @yield Block to execute if not cached
+        # @return [Object] Cached or freshly fetched value
+        def fetch(cache_key, &block)
+          return yield unless enabled?
+
+          cache = current_cache
+          return cache[cache_key] if cache.key?(cache_key)
+
+          cache[cache_key] = yield
+        end
+
+        # Check if request caching is active
+        def enabled?
+          Thread.current[:subflag_request_cache].is_a?(Hash)
+        end
+
+        # Start a new cache scope
+        def start
+          Thread.current[:subflag_request_cache] = {}
+        end
+
+        # End the cache scope
+        def clear
+          Thread.current[:subflag_request_cache] = nil
+        end
+
+        # Get current cache
+        def current_cache
+          Thread.current[:subflag_request_cache] ||= {}
+        end
+
+        # Get cache stats for debugging
+        def stats
+          cache = current_cache
+          { size: cache.size, keys: cache.keys }
+        end
+      end
+
+      # Rack middleware for per-request caching
+      #
+      # Wraps each request in a cache scope so flag evaluations
+      # are cached for the duration of the request.
+      #
+      class Middleware
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          RequestCache.start
+          @app.call(env)
+        ensure
+          RequestCache.clear
+        end
+      end
+    end
+  end
+end

data/lib/subflag/rails/test_helpers.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # Test helpers for stubbing feature flags in specs
+    #
+    # @example RSpec setup
+    #   # spec/rails_helper.rb
+    #   require "subflag/rails/test_helpers"
+    #   RSpec.configure do |config|
+    #     config.include Subflag::Rails::TestHelpers
+    #   end
+    #
+    # @example Minitest setup
+    #   # test/test_helper.rb
+    #   require "subflag/rails/test_helpers"
+    #   class ActiveSupport::TestCase
+    #     include Subflag::Rails::TestHelpers
+    #   end
+    #
+    # @example Usage
+    #   it "shows new checkout when enabled" do
+    #     stub_subflag(:new_checkout, true)
+    #     visit checkout_path
+    #     expect(page).to have_content("New Checkout")
+    #   end
+    #
+    #   it "limits projects based on plan" do
+    #     stub_subflag(:max_projects, 100)
+    #     expect(subflag_value(:max_projects, default: 3)).to eq(100)
+    #   end
+    #
+    module TestHelpers
+      # Stub a flag to return a specific value
+      #
+      # @param flag_name [Symbol, String] The flag name (underscores or dashes)
+      # @param value [Object] The value to return
+      #
+      # @example Boolean
+      #   stub_subflag(:new_checkout, true)
+      #
+      # @example String
+      #   stub_subflag(:headline, "Welcome!")
+      #
+      # @example Integer
+      #   stub_subflag(:max_projects, 100)
+      #
+      # @example Hash
+      #   stub_subflag(:limits, { max_items: 50 })
+      #
+      def stub_subflag(flag_name, value)
+        flag_key = normalize_flag_key(flag_name)
+        stubbed_flags[flag_key] = value
+      end
+
+      # Stub multiple flags at once
+      #
+      # @param flags [Hash] Flag names to values
+      #
+      # @example
+      #   stub_subflags(
+      #     new_checkout: true,
+      #     max_projects: 100,
+      #     headline: "Welcome!"
+      #   )
+      #
+      def stub_subflags(flags)
+        flags.each { |name, value| stub_subflag(name, value) }
+      end
+
+      # Clear all stubbed flags
+      def clear_stubbed_subflags
+        stubbed_flags.clear
+      end
+
+      private
+
+      def stubbed_flags
+        @stubbed_flags ||= {}
+      end
+
+      def normalize_flag_key(flag_name)
+        flag_name.to_s.tr("_", "-")
+      end
+    end
+
+    # Stubbed client that returns test values
+    class StubbedClient
+      def initialize(stubs)
+        @stubs = stubs
+      end
+
+      def enabled?(flag_key, user: nil, context: nil, default: false)
+        @stubs.fetch(flag_key, default)
+      end
+
+      def value(flag_key, user: nil, context: nil, default:)
+        @stubs.fetch(flag_key, default)
+      end
+
+      def evaluate(flag_key, user: nil, context: nil, default:)
+        value = @stubs.fetch(flag_key, default)
+        EvaluationResult.new(
+          value: value,
+          variant: "stubbed",
+          reason: @stubs.key?(flag_key) ? :static : :default,
+          flag_key: flag_key
+        )
+      end
+    end
+  end
+end
+
+# Patch FlagAccessor to use stubbed values in tests
+module Subflag
+  module Rails
+    class FlagAccessor
+      private
+
+      alias_method :original_client, :client
+
+      def client
+        if test_stubs_active?
+          StubbedClient.new(current_test_stubs)
+        else
+          original_client
+        end
+      end
+
+      def test_stubs_active?
+        Thread.current[:subflag_test_stubs].is_a?(Hash) &&
+          !Thread.current[:subflag_test_stubs].empty?
+      end
+
+      def current_test_stubs
+        Thread.current[:subflag_test_stubs] || {}
+      end
+    end
+
+    # Update TestHelpers to use thread-local storage
+    module TestHelpers
+      private
+
+      def stubbed_flags
+        Thread.current[:subflag_test_stubs] ||= {}
+      end
+    end
+  end
+end

data/lib/subflag/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    VERSION = "0.1.0"
+  end
+end