subflag-rails 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b994b3be254b327ab4c2d7f94ed4a30a9af6a47af2c19b58089b02b5d8487e5
-  data.tar.gz: 267fb6f5df4a770f7133ee475ae364118bc2459031137434160cf17ddf91033c
+  metadata.gz: da40f567a605d55076aaeabed1edd404bb41ba2a1703c56595e42611ebf4aaa4
+  data.tar.gz: 39df667c30500ebf560e90694213f05b479d60f488575c7f2503409bc640222d
 SHA512:
-  metadata.gz: bda7f1465a5f3eabf2baa0190c372c4687b731ad5cb43a9d11851b78b9d23457c9dbdffb65f2235f92f61b18841ed1bddc8d5b6eae27d89ac4b9802db6b81df3
-  data.tar.gz: 950362e174920f95c08309a8cfc406e1249612f554f0cd51df13f580c8f6a73492cca56e2ff597dcba94fbb6914d66e069569a23c5df0c139ded9c7983561860
+  metadata.gz: 0bb2499ecf945fb2586918f5c3e57cdda5e6ce2f143eb4b6d1d674370412ccee6f6e8fe5d992705ac4b0b28de88465ebe7e140fad1a2c71f691982ebe363c4ce
+  data.tar.gz: f255c179b502557624bfcfc81bc06743c13898bef9d7b5225e4519e097fbdfc7b88af2b2729088883747cb3a123f1a51fff521618527e68e7e77ca494212be32

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

@@ -1,6 +1,25 @@
 # Subflag Rails
 
-Typed feature flags for Rails. Booleans, strings, numbers, and JSON — all targetable by user.
+Typed feature flags for Rails. Booleans, strings, numbers, and JSON — with pluggable backends.
+
+[Subflag](https://subflag.com)
+
+## Backends
+
+Choose where your flags live:
+
+| Backend | Use Case | Flags Stored In |
+|---------|----------|-----------------|
+| `:subflag` | Production with dashboard, environments, targeting | Subflag Cloud |
+| `:active_record` | Self-hosted, no external dependencies | Your database |
+| `:memory` | Testing and development | In-memory hash |
+
+**Same API regardless of backend:**
+
+```ruby
+subflag_enabled?(:new_checkout)           # Works with any backend
+subflag_value(:max_projects, default: 3)  # Works with any backend
+```
 
 ## Installation
 
@@ -8,9 +27,14 @@ Add to your Gemfile:
 
 ```ruby
 gem 'subflag-rails'
+
+# If using Subflag Cloud (backend: :subflag), also add:
+gem 'subflag-openfeature-provider'
 ```
 
-Run the generator:
+### Option 1: Subflag Cloud (Default)
+
+Dashboard, environments, percentage rollouts, and user targeting.
 
 ```bash
 rails generate subflag:install
@@ -29,6 +53,38 @@ subflag:
 
 Or set the `SUBFLAG_API_KEY` environment variable.
 
+### Option 2: ActiveRecord (Self-Hosted)
+
+Flags stored in your database. No external dependencies.
+
+```bash
+rails generate subflag:install --backend=active_record
+rails db:migrate
+```
+
+Create flags directly:
+
+```ruby
+Subflag::Rails::Flag.create!(key: "new-checkout", value: "true", value_type: "boolean")
+Subflag::Rails::Flag.create!(key: "max-projects", value: "100", value_type: "integer")
+Subflag::Rails::Flag.create!(key: "welcome-message", value: "Hello!", value_type: "string")
+```
+
+### Option 3: Memory (Testing)
+
+In-memory flags for tests and local development.
+
+```bash
+rails generate subflag:install --backend=memory
+```
+
+Set flags programmatically:
+
+```ruby
+Subflag::Rails.provider.set(:new_checkout, true)
+Subflag::Rails.provider.set(:max_projects, 100)
+```
+
 ## Usage
 
 ### Controllers & Views
@@ -159,82 +215,190 @@ In Ruby, use underscores — they're automatically converted to dashes:
 subflag_enabled?(:new_checkout)  # looks up "new-checkout"
 ```
 
-## Testing
+## Request Caching
 
-Stub flags in your tests:
+Enable per-request caching to avoid multiple API calls for the same flag:
 
 ```ruby
-# spec/rails_helper.rb (RSpec)
-require "subflag/rails/test_helpers"
-RSpec.configure do |config|
-  config.include Subflag::Rails::TestHelpers
-end
+# config/application.rb
+config.middleware.use Subflag::Rails::RequestCache::Middleware
+```
 
-# test/test_helper.rb (Minitest)
-require "subflag/rails/test_helpers"
-class ActiveSupport::TestCase
-  include Subflag::Rails::TestHelpers
+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
+```
+
+## 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.
+
+## 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
-# In your specs/tests
-it "shows new checkout when enabled" do
-  stub_subflag(:new_checkout, true)
-  stub_subflag(:max_projects, 100)
+# config/application.rb (required)
+config.middleware.use Subflag::Rails::RequestCache::Middleware
+```
 
-  visit checkout_path
-  expect(page).to have_content("New Checkout")
+```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
+```
 
-# Stub multiple at once
-stub_subflags(
-  new_checkout: true,
-  max_projects: 100,
-  headline: "Welcome!"
-)
+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
 ```
 
-## Request Caching
+### How It Works
 
-Enable per-request caching to avoid multiple API calls for the same flag:
+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
-# config/application.rb
-config.middleware.use Subflag::Rails::RequestCache::Middleware
+# No user context
+subflag_prefetch(nil)
+
+# With specific user
+subflag_prefetch(admin_user)
+
+# With additional context
+subflag_prefetch(current_user, context: { device: "mobile" })
 ```
 
-Now multiple checks for the same flag in one request hit the API only once:
+### Direct API
+
+You can also use the module method directly:
 
 ```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
+Subflag.prefetch_flags(user: current_user)
+# or
+Subflag::Rails.prefetch_flags(user: current_user)
 ```
 
 ## Configuration
 
 ```ruby
 Subflag::Rails.configure do |config|
-  # API key (auto-loaded from credentials/ENV)
+  # Backend: :subflag (cloud), :active_record (self-hosted), :memory (testing)
+  config.backend = :subflag
+
+  # API key - required for :subflag backend
   config.api_key = "sdk-production-..."
 
   # API URL (default: https://api.subflag.com)
   config.api_url = "https://api.subflag.com"
 
+  # Cross-request caching via Rails.cache (optional, :subflag backend only)
+  # 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
 
-  # User context
+  # User context - works with all backends
   config.user_context do |user|
     { targeting_key: user.id.to_s, plan: user.plan }
   end
 end
 ```
 
+### ActiveRecord Flag Model
+
+When using `backend: :active_record`, flags are stored in the `subflag_flags` table:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `key` | string | Flag name (lowercase, dashes, e.g., `new-checkout`) |
+| `value` | text | The flag value as a string |
+| `value_type` | string | Type: `boolean`, `string`, `integer`, `float`, `object` |
+| `enabled` | boolean | Whether the flag is active (default: true) |
+| `description` | text | Optional description |
+
+```ruby
+# Create flags
+Subflag::Rails::Flag.create!(key: "max-projects", value: "100", value_type: "integer")
+
+# Query flags
+Subflag::Rails::Flag.enabled.find_each { |f| puts "#{f.key}: #{f.typed_value}" }
+
+# Disable a flag
+Subflag::Rails::Flag.find_by(key: "new-checkout")&.update!(enabled: false)
+```
+
+## 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!"
+)
+```
+
 ## Documentation
 
 - [Subflag Docs](https://docs.subflag.com)

data/lib/generators/subflag/install_generator.rb

@@ -7,49 +7,113 @@ module Subflag
     # Generator for setting up Subflag in a Rails application
     #
     # Usage:
-    #   rails generate subflag:install
+    #   rails generate subflag:install                     # Default: Subflag Cloud
+    #   rails generate subflag:install --backend=subflag   # Explicit: Subflag Cloud
+    #   rails generate subflag:install --backend=active_record  # Self-hosted DB
+    #   rails generate subflag:install --backend=memory    # Testing only
     #
     class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration if defined?(::Rails::Generators::Migration)
+
       source_root File.expand_path("templates", __dir__)
 
-      desc "Creates a Subflag initializer and provides setup instructions"
+      desc "Creates a Subflag initializer and optionally a migration for ActiveRecord backend"
+
+      class_option :backend, type: :string, default: "subflag",
+                   desc: "Backend to use: subflag (cloud), active_record (self-hosted), or memory (testing)"
+
+      def self.next_migration_number(dirname)
+        if defined?(::ActiveRecord::Generators::Base)
+          ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+        else
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        end
+      end
 
       def create_initializer
-        template "initializer.rb", "config/initializers/subflag.rb"
+        template "initializer.rb.tt", "config/initializers/subflag.rb"
+      end
+
+      def create_migration
+        return unless options[:backend] == "active_record"
+
+        migration_template "create_subflag_flags.rb.tt",
+                          "db/migrate/create_subflag_flags.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 ""
+
+        case options[:backend]
+        when "active_record"
+          say "Subflag installed with ActiveRecord backend!", :green
+          say ""
+          say "Next steps:"
+          say ""
+          say "1. Run the migration:"
+          say "   $ rails db:migrate"
+          say ""
+          say "2. Create your first flag:"
+          say ""
+          say "   Subflag::Rails::Flag.create!("
+          say "     key: 'new-checkout',"
+          say "     value: 'true',"
+          say "     value_type: 'boolean'"
+          say "   )"
+          say ""
+          say "3. Use flags in your code:"
+          say ""
+          say "   if subflag_enabled?(:new_checkout)"
+          say "     # ..."
+          say "   end"
+          say ""
+          say "When you're ready for a dashboard, environments, and user targeting:"
+          say "  https://subflag.com", :yellow
+          say ""
+
+        when "memory"
+          say "Subflag installed with Memory backend!", :green
+          say ""
+          say "Note: Memory backend is for testing only. Flags reset on restart."
+          say ""
+          say "Set flags in your tests or initializer:"
+          say ""
+          say "  Subflag::Rails.provider.set(:new_checkout, true)"
+          say "  Subflag::Rails.provider.set(:max_projects, 100)"
+          say ""
+          say "Use flags:"
+          say ""
+          say "  subflag_enabled?(:new_checkout)        # => true"
+          say "  subflag_value(:max_projects, default: 3)  # => 100"
+          say ""
+
+        else # subflag (cloud)
+          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 "Docs: https://docs.subflag.com/rails"
+          say ""
+        end
       end
     end
   end

data/lib/generators/subflag/templates/create_subflag_flags.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class CreateSubflagFlags < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :subflag_flags do |t|
+      t.string :key, null: false
+      t.string :value_type, null: false, default: "boolean"
+      t.text :value, null: false
+      t.boolean :enabled, null: false, default: true
+      t.text :description
+
+      t.timestamps
+    end
+
+    add_index :subflag_flags, :key, unique: true
+  end
+end

data/lib/generators/subflag/templates/{initializer.rb → initializer.rb.tt}

@@ -2,17 +2,31 @@
 
 # Subflag configuration
 #
+<% if options[:backend] == "subflag" -%>
 # API key is automatically loaded from:
 # 1. Rails credentials (subflag.api_key or subflag_api_key)
 # 2. SUBFLAG_API_KEY environment variable
+<% elsif options[:backend] == "active_record" -%>
+# Using ActiveRecord backend - flags stored in subflag_flags table
+<% else -%>
+# Using Memory backend - flags stored in memory (testing only)
+<% end -%>
 
 Subflag::Rails.configure do |config|
-  # Uncomment to manually set API key
-  # config.api_key = Rails.application.credentials.dig(:subflag, :api_key)
+  # Backend: :subflag (cloud), :active_record (self-hosted), :memory (testing)
+  config.backend = :<%= options[:backend] %>
+<% if options[:backend] == "subflag" -%>
+
+  # Your Subflag API key
+  # Get one at https://subflag.com
+  config.api_key = ENV["SUBFLAG_API_KEY"] || Rails.application.credentials.dig(:subflag, :api_key)
+<% end -%>
+<% if options[:backend] != "memory" -%>
 
   # Enable logging in development
   config.logging_enabled = Rails.env.development?
   config.log_level = :debug
+<% end -%>
 
   # Configure user context for targeting
   # This enables per-user flag values (e.g., different limits by plan)

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    module Backends
+      # Provider that reads flags from your Rails database
+      #
+      # Stores flags in a `subflag_flags` table with typed values.
+      # Perfect for teams who want self-hosted feature flags without external dependencies.
+      #
+      # @example
+      #   Subflag::Rails.configure do |config|
+      #     config.backend = :active_record
+      #   end
+      #
+      #   # Create a flag
+      #   Subflag::Rails::Flag.create!(
+      #     key: "max-projects",
+      #     value: "100",
+      #     value_type: "integer",
+      #     enabled: true
+      #   )
+      #
+      #   # Use it
+      #   subflag_value(:max_projects, default: 3)  # => 100
+      #
+      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)
+        end
+
+        def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+          resolve(flag_key, default_value, :string)
+        end
+
+        def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+          resolve(flag_key, default_value, :number)
+        end
+
+        def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+          resolve(flag_key, default_value, :integer)
+        end
+
+        def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+          resolve(flag_key, default_value, :float)
+        end
+
+        def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+          resolve(flag_key, default_value, :object)
+        end
+
+        private
+
+        def resolve(flag_key, default_value, expected_type)
+          flag = Subflag::Rails::Flag.find_by(key: flag_key)
+
+          unless flag&.enabled?
+            return resolution(default_value, reason: :default)
+          end
+
+          value = flag.typed_value(expected_type)
+          resolution(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