subflag-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1796467214a7c83cd0187601d5298c6b5aae3397b6b0f48122d0daecae7a78fa
+  data.tar.gz: 58ca3b9ba465a7ce5f4be64df8a37dc88dc98a51ee9f7411d7e35856cd419beb
+SHA512:
+  metadata.gz: 2abda5d0854287dbada9fd0205552525baa8e5d27a7924660656009cf516c2c38a3b37aba246a39dc688896a5fec053c2d32544eda6d83aef05824893472a2a1
+  data.tar.gz: f08bbb6c48fc8f61f24c3e9846aa6aa53276f5cbdb4ef4b165b230eeffd948e26e7f5477bee2c63b4b1b65b2d09decf4be0c5999db2f2afd81e06bc8e35d7abb

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2025-11-30
+
+### Added
+
+- Initial release
+- `Subflag.flags` DSL with method_missing for clean flag access
+- Boolean flags with `?` suffix (e.g., `flags.new_checkout?`)
+- Typed value flags with required defaults
+- `subflag_enabled?` and `subflag_value` helpers for controllers and views
+- `subflag_for` helper to get a flag accessor
+- Auto-scoping to `current_user` in controllers and views
+- User context configuration for targeting
+- Rails generator (`rails g subflag:install`)
+- Auto-configuration from Rails credentials and ENV
+- Bracket access for exact flag names
+- `evaluate` method for full evaluation details
+- Logging support with configurable levels

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Subflag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,245 @@
+# Subflag Rails
+
+Typed feature flags for Rails. Booleans, strings, numbers, and JSON — all targetable by user.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'subflag-rails'
+```
+
+Run the generator:
+
+```bash
+rails generate subflag:install
+```
+
+Add your API key to Rails credentials:
+
+```bash
+rails credentials:edit
+```
+
+```yaml
+subflag:
+  api_key: sdk-production-your-key-here
+```
+
+Or set the `SUBFLAG_API_KEY` environment variable.
+
+## Usage
+
+### Controllers & Views
+
+Helpers are automatically available and scoped to `current_user`:
+
+```ruby
+# 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
+```
+
+```erb
+<!-- View -->
+<% if subflag_enabled?(:new_checkout) %>
+  <%= render "new_checkout" %>
+<% end %>
+
+<h1><%= subflag_value(:headline, default: "Welcome") %></h1>
+
+<p>You can create <%= subflag_value(:max_projects, default: 3) %> projects</p>
+```
+
+### Flag Accessor DSL
+
+For multiple flag checks, use the flag accessor:
+
+```ruby
+flags = subflag_for  # auto-scoped to current_user
+
+if flags.beta_feature?
+  headline = flags.welcome_message(default: "Hello!")
+  max = flags.max_projects(default: 3)
+end
+```
+
+Or use `Subflag.flags` directly:
+
+```ruby
+# With user context
+flags = Subflag.flags(user: current_user)
+flags.new_checkout?              # => true/false
+flags.max_projects(default: 3)   # => 100
+
+# Bracket access for exact flag names
+flags["my-exact-flag", default: "value"]
+
+# Full evaluation details
+result = flags.evaluate(:max_projects, default: 3)
+result.value    # => 100
+result.variant  # => "premium"
+result.reason   # => :targeting_match
+```
+
+### Flag Types
+
+The default value determines the expected type:
+
+```ruby
+# Boolean (? suffix, default optional)
+subflag_enabled?(:new_checkout)           # default: false
+subflag_enabled?(:new_checkout, default: true)
+
+# String
+subflag_value(:headline, default: "Welcome")
+
+# Integer
+subflag_value(:max_projects, default: 3)
+
+# Float
+subflag_value(:tax_rate, default: 0.08)
+
+# Hash/Object
+subflag_value(:feature_limits, default: { max_items: 10 })
+```
+
+### User Targeting
+
+Configure how to extract context from user objects:
+
+```ruby
+# config/initializers/subflag.rb
+Subflag::Rails.configure do |config|
+  config.user_context do |user|
+    {
+      targeting_key: user.id.to_s,
+      email: user.email,
+      plan: user.subscription&.plan_name || "free",
+      admin: user.admin?
+    }
+  end
+end
+```
+
+Now flags can return different values based on user attributes:
+
+```ruby
+# In Subflag dashboard: max-projects returns 3 for "free", 100 for "premium"
+subflag_value(:max_projects, default: 3)  # => 3 or 100 based on user's plan
+```
+
+### Override User Context
+
+```ruby
+# No user context
+subflag_enabled?(:public_feature, user: nil)
+
+# Different user
+subflag_value(:max_projects, user: admin_user, default: 3)
+```
+
+## Flag Naming
+
+Flag names use lowercase letters, numbers, and dashes:
+- Valid: `new-checkout`, `max-api-requests`, `feature1`
+- Invalid: `new_checkout`, `NewCheckout`, `my flag`
+
+In Ruby, use underscores — they're automatically converted to dashes:
+
+```ruby
+subflag_enabled?(:new_checkout)  # looks up "new-checkout"
+```
+
+## Testing
+
+Stub flags in your tests:
+
+```ruby
+# spec/rails_helper.rb (RSpec)
+require "subflag/rails/test_helpers"
+RSpec.configure do |config|
+  config.include Subflag::Rails::TestHelpers
+end
+
+# test/test_helper.rb (Minitest)
+require "subflag/rails/test_helpers"
+class ActiveSupport::TestCase
+  include Subflag::Rails::TestHelpers
+end
+```
+
+```ruby
+# In your specs/tests
+it "shows new checkout when enabled" do
+  stub_subflag(:new_checkout, true)
+  stub_subflag(:max_projects, 100)
+
+  visit checkout_path
+  expect(page).to have_content("New Checkout")
+end
+
+# Stub multiple at once
+stub_subflags(
+  new_checkout: true,
+  max_projects: 100,
+  headline: "Welcome!"
+)
+```
+
+## Request Caching
+
+Enable per-request caching to avoid multiple API calls for the same flag:
+
+```ruby
+# config/application.rb
+config.middleware.use Subflag::Rails::RequestCache::Middleware
+```
+
+Now multiple checks for the same flag in one request hit the API only once:
+
+```ruby
+# Without caching: 3 API calls
+# With caching: 1 API call (cached for subsequent checks)
+subflag_enabled?(:new_checkout)  # API call
+subflag_enabled?(:new_checkout)  # Cache hit
+subflag_enabled?(:new_checkout)  # Cache hit
+```
+
+## Configuration
+
+```ruby
+Subflag::Rails.configure do |config|
+  # API key (auto-loaded from credentials/ENV)
+  config.api_key = "sdk-production-..."
+
+  # API URL (default: https://api.subflag.com)
+  config.api_url = "https://api.subflag.com"
+
+  # Logging
+  config.logging_enabled = Rails.env.development?
+  config.log_level = :debug  # :debug, :info, :warn
+
+  # User context
+  config.user_context do |user|
+    { targeting_key: user.id.to_s, plan: user.plan }
+  end
+end
+```
+
+## Documentation
+
+- [Subflag Docs](https://docs.subflag.com)
+- [Rails Guide](https://docs.subflag.com/rails)
+
+## License
+
+MIT

data/lib/generators/subflag/install_generator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Subflag
+  module Generators
+    # Generator for setting up Subflag in a Rails application
+    #
+    # Usage:
+    #   rails generate subflag:install
+    #
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Subflag initializer and provides setup instructions"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/subflag.rb"
+      end
+
+      def show_instructions
+        say ""
+        say "Subflag installed!", :green
+        say ""
+        say "Next steps:"
+        say ""
+        say "1. Add your API key to Rails credentials:"
+        say "   $ rails credentials:edit"
+        say ""
+        say "   subflag:"
+        say "     api_key: sdk-production-your-key-here"
+        say ""
+        say "   Or set SUBFLAG_API_KEY environment variable."
+        say ""
+        say "2. Configure user context in config/initializers/subflag.rb"
+        say ""
+        say "3. Use flags in your code:"
+        say ""
+        say "   # Controller (auto-scoped to current_user)"
+        say "   if subflag_enabled?(:new_checkout)"
+        say "     # ..."
+        say "   end"
+        say ""
+        say "   max = subflag_value(:max_projects, default: 3)"
+        say ""
+        say "   # View"
+        say "   <% if subflag_enabled?(:new_checkout) %>"
+        say "     <%= render 'new_checkout' %>"
+        say "   <% end %>"
+        say ""
+        say "Docs: https://docs.subflag.com/rails"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/subflag/templates/initializer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Subflag configuration
+#
+# API key is automatically loaded from:
+# 1. Rails credentials (subflag.api_key or subflag_api_key)
+# 2. SUBFLAG_API_KEY environment variable
+
+Subflag::Rails.configure do |config|
+  # Uncomment to manually set API key
+  # config.api_key = Rails.application.credentials.dig(:subflag, :api_key)
+
+  # Enable logging in development
+  config.logging_enabled = Rails.env.development?
+  config.log_level = :debug
+
+  # Configure user context for targeting
+  # This enables per-user flag values (e.g., different limits by plan)
+  #
+  # config.user_context do |user|
+  #   {
+  #     targeting_key: user.id.to_s,
+  #     email: user.email,
+  #     plan: user.subscription&.plan_name || "free",
+  #     admin: user.admin?
+  #   }
+  # end
+end

data/lib/subflag/rails/client.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # Client for evaluating feature flags
+    #
+    # This is the low-level client used by FlagAccessor.
+    # Most users should use `Subflag.flags` instead.
+    #
+    class Client
+      # Check if a boolean flag is enabled
+      #
+      # @param flag_key [String] The flag key (already normalized)
+      # @param user [Object, nil] The user object for targeting
+      # @param context [Hash, nil] Additional context attributes
+      # @param default [Boolean] Default value if flag not found (defaults to false)
+      # @return [Boolean]
+      def enabled?(flag_key, user: nil, context: nil, default: false)
+        ctx = ContextBuilder.build(user: user, context: context)
+        cache_key = build_cache_key(flag_key, ctx, :boolean)
+
+        result = RequestCache.fetch(cache_key) do
+          openfeature_client.fetch_boolean_value(flag_key, default, ctx)
+        end
+
+        log_evaluation(flag_key, result, default)
+        result
+      end
+
+      # Get a flag value - default is required to determine type
+      #
+      # @param flag_key [String] The flag key (already normalized)
+      # @param user [Object, nil] The user object for targeting
+      # @param context [Hash, nil] Additional context attributes
+      # @param default [Object] Default value (required - determines expected type)
+      # @return [Object] The flag value
+      # @raise [ArgumentError] If default is nil
+      def value(flag_key, user: nil, context: nil, default:)
+        ctx = ContextBuilder.build(user: user, context: context)
+        cache_key = build_cache_key(flag_key, ctx, default.class)
+
+        result = RequestCache.fetch(cache_key) do
+          fetch_value_by_type(flag_key, default, ctx)
+        end
+
+        log_evaluation(flag_key, result, default)
+        result
+      end
+
+      # Evaluate a flag and get full details - default is required
+      #
+      # @param flag_key [String] The flag key (already normalized)
+      # @param user [Object, nil] The user object for targeting
+      # @param context [Hash, nil] Additional context attributes
+      # @param default [Object] Default value (required - determines expected type)
+      # @return [EvaluationResult] Full evaluation result
+      # @raise [ArgumentError] If default is nil
+      def evaluate(flag_key, user: nil, context: nil, default:)
+        ctx = ContextBuilder.build(user: user, context: context)
+        cache_key = build_cache_key(flag_key, ctx, "details:#{default.class}")
+
+        details = RequestCache.fetch(cache_key) do
+          fetch_details_by_type(flag_key, default, ctx)
+        end
+
+        log_evaluation(flag_key, details[:value], default)
+        EvaluationResult.from_openfeature(details, flag_key: flag_key)
+      end
+
+      private
+
+      def build_cache_key(flag_key, ctx, type)
+        context_hash = ctx ? ctx.hash : "no_context"
+        "subflag:#{flag_key}:#{context_hash}:#{type}"
+      end
+
+      def openfeature_client
+        @openfeature_client ||= OpenFeature::SDK.build_client
+      end
+
+      def fetch_value_by_type(flag_key, default, ctx)
+        case default
+        when String
+          openfeature_client.fetch_string_value(flag_key, default, ctx)
+        when Integer
+          openfeature_client.fetch_integer_value(flag_key, default, ctx)
+        when Float
+          openfeature_client.fetch_float_value(flag_key, default, ctx)
+        when TrueClass, FalseClass
+          openfeature_client.fetch_boolean_value(flag_key, default, ctx)
+        when Hash
+          openfeature_client.fetch_object_value(flag_key, default, ctx)
+        when NilClass
+          raise ArgumentError, "default is required for value flags (it determines the expected type)"
+        else
+          raise ArgumentError, "Unsupported default type: #{default.class}. Use String, Integer, Float, Boolean, or Hash."
+        end
+      end
+
+      def fetch_details_by_type(flag_key, default, ctx)
+        case default
+        when String
+          openfeature_client.fetch_string_details(flag_key, default, ctx)
+        when Integer
+          openfeature_client.fetch_integer_details(flag_key, default, ctx)
+        when Float
+          openfeature_client.fetch_float_details(flag_key, default, ctx)
+        when TrueClass, FalseClass
+          openfeature_client.fetch_boolean_details(flag_key, default, ctx)
+        when Hash
+          openfeature_client.fetch_object_details(flag_key, default, ctx)
+        when NilClass
+          raise ArgumentError, "default is required for evaluate (it determines the expected type)"
+        else
+          raise ArgumentError, "Unsupported default type: #{default.class}. Use String, Integer, Float, Boolean, or Hash."
+        end
+      end
+
+      def configuration
+        Subflag::Rails.configuration
+      end
+
+      def log_evaluation(flag_key, result, default)
+        return unless configuration.logging_enabled
+
+        logger = defined?(::Rails.logger) ? ::Rails.logger : nil
+        return unless logger
+
+        message = "[Subflag] #{flag_key} = #{result.inspect}"
+        message += " (default)" if result == default
+
+        case configuration.log_level
+        when :info
+          logger.info(message)
+        when :warn
+          logger.warn(message)
+        else
+          logger.debug(message)
+        end
+      end
+    end
+  end
+end

data/lib/subflag/rails/configuration.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # Configuration for Subflag Rails integration
+    #
+    # @example Basic configuration
+    #   Subflag::Rails.configure do |config|
+    #     config.api_key = Rails.application.credentials.subflag_api_key
+    #   end
+    #
+    # @example With user context
+    #   Subflag::Rails.configure do |config|
+    #     config.api_key = Rails.application.credentials.subflag_api_key
+    #     config.user_context do |user|
+    #       {
+    #         targeting_key: user.id.to_s,
+    #         email: user.email,
+    #         plan: user.subscription&.plan_name,
+    #         admin: user.admin?
+    #       }
+    #     end
+    #   end
+    #
+    class Configuration
+      # @return [String, nil] The Subflag API key
+      attr_accessor :api_key
+
+      # @return [String] The Subflag API URL (defaults to production)
+      attr_accessor :api_url
+
+      # @return [Boolean] Whether to log flag evaluations
+      attr_accessor :logging_enabled
+
+      # @return [Symbol] Log level for flag evaluations (:debug, :info, :warn)
+      attr_accessor :log_level
+
+      def initialize
+        @api_key = nil
+        @api_url = "https://api.subflag.com"
+        @user_context_block = nil
+        @logging_enabled = false
+        @log_level = :debug
+      end
+
+      # Configure how to extract context from a user object
+      #
+      # @yield [user] Block that receives a user object and returns context hash
+      # @yieldparam user [Object] The user object passed to flag methods
+      # @yieldreturn [Hash] Context hash with targeting_key and attributes
+      #
+      # @example
+      #   config.user_context do |user|
+      #     {
+      #       targeting_key: user.id.to_s,
+      #       email: user.email,
+      #       plan: user.plan
+      #     }
+      #   end
+      def user_context(&block)
+        @user_context_block = block if block_given?
+        @user_context_block
+      end
+
+      # Check if user context is configured
+      #
+      # @return [Boolean]
+      def user_context_configured?
+        !@user_context_block.nil?
+      end
+
+      # Build context from a user object using the configured block
+      #
+      # @param user [Object] The user object
+      # @return [Hash, nil] The context hash or nil if no user/block
+      def build_user_context(user)
+        return nil unless user && @user_context_block
+
+        @user_context_block.call(user)
+      end
+    end
+  end
+end

data/lib/subflag/rails/context_builder.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # Builds OpenFeature evaluation context from user objects and additional attributes
+    class ContextBuilder
+      # Build an OpenFeature context hash
+      #
+      # @param user [Object, nil] The user object for targeting
+      # @param context [Hash, nil] Additional context attributes
+      # @return [Hash, nil] The combined context or nil if empty
+      def self.build(user: nil, context: nil)
+        new(user: user, context: context).build
+      end
+
+      def initialize(user: nil, context: nil)
+        @user = user
+        @context = context || {}
+      end
+
+      # Build the context hash
+      #
+      # @return [Hash, nil]
+      def build
+        result = {}
+
+        # Add user context if configured
+        if @user
+          user_context = configuration.build_user_context(@user)
+          result.merge!(user_context) if user_context
+        end
+
+        # Merge in additional context (overrides user context)
+        result.merge!(@context) if @context.is_a?(Hash)
+
+        # Return nil if empty (no context to send)
+        result.empty? ? nil : normalize_context(result)
+      end
+
+      private
+
+      def configuration
+        Subflag::Rails.configuration
+      end
+
+      # Normalize context to OpenFeature format
+      #
+      # @param ctx [Hash] The raw context
+      # @return [Hash] Normalized context with targeting_key at top level
+      def normalize_context(ctx)
+        # Ensure targeting_key is a string
+        if ctx[:targeting_key]
+          ctx[:targeting_key] = ctx[:targeting_key].to_s
+        elsif ctx["targeting_key"]
+          ctx[:targeting_key] = ctx.delete("targeting_key").to_s
+        end
+
+        ctx.transform_keys(&:to_sym)
+      end
+    end
+  end
+end