subflag-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d5585ee53dcf0c1864f3d9bf5845a41cd8e3c884fe11ca457bc51b3ded8cfcd
-  data.tar.gz: 1014353a80ee041027dd501aea4035f7043b873dbf75506678e2852b948f436a
+  metadata.gz: da40f567a605d55076aaeabed1edd404bb41ba2a1703c56595e42611ebf4aaa4
+  data.tar.gz: 39df667c30500ebf560e90694213f05b479d60f488575c7f2503409bc640222d
 SHA512:
-  metadata.gz: 7a0b5adb5b8df94ed4e07ba41e47b4430b719b2cf741695b6f9029239aefa6437535d36fb08d9b2f12d84911126cdfa45d15429b2c024f0d93c694f6ee5e77e8
-  data.tar.gz: 582032e633830bb9e5867ae6883545a4ba5fd0ece16556a542f9de3513a5c0853f4ce7a121ad4af3d3ea6bc901ff136abc9f77f12eaa37789d64fa77bd11a750
+  metadata.gz: 0bb2499ecf945fb2586918f5c3e57cdda5e6ce2f143eb4b6d1d674370412ccee6f6e8fe5d992705ac4b0b28de88465ebe7e140fad1a2c71f691982ebe363c4ce
+  data.tar.gz: f255c179b502557624bfcfc81bc06743c13898bef9d7b5225e4519e097fbdfc7b88af2b2729088883747cb3a123f1a51fff521618527e68e7e77ca494212be32

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,42 +215,6 @@ In Ruby, use underscores — they're automatically converted to dashes:
 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:
@@ -214,6 +234,25 @@ 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:
@@ -263,25 +302,6 @@ subflag_prefetch(admin_user)
 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:
@@ -296,13 +316,16 @@ Subflag::Rails.prefetch_flags(user: current_user)
 
 ```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)
+  # Cross-request caching via Rails.cache (optional, :subflag backend only)
   # When set, prefetched flags are cached for this duration
   config.cache_ttl = 30.seconds
 
@@ -310,13 +333,72 @@ Subflag::Rails.configure do |config|
   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

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,6 +2,10 @@
 
 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.
@@ -10,8 +14,11 @@ module Subflag
     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.
+      # 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
@@ -23,16 +30,17 @@ module Subflag
       #   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)
+        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
-
-        # Otherwise fetch directly from API (per-request cache only)
-        prefetch_from_api(ctx, context_hash)
       end
 
       # Check if a boolean flag is enabled
@@ -121,6 +129,20 @@ 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)
@@ -151,7 +173,7 @@ module Subflag
         cached_data
       end
 
-      # Populate RequestCache from cached hash data
+      # Populate RequestCache from cached hash data (Subflag API)
       def populate_request_cache_from_data(data_array, context_hash)
         return unless RequestCache.enabled?
 
@@ -161,6 +183,30 @@ module Subflag
         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}"

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
 
@@ -41,6 +49,7 @@ module Subflag
       attr_accessor :cache_ttl
 
       def initialize
+        @backend = :subflag
         @api_key = nil
         @api_url = "https://api.subflag.com"
         @user_context_block = nil
@@ -49,6 +58,19 @@ module Subflag
         @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]

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.3.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/subflag/rails.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "open_feature/sdk"
-require "subflag"
 
 require_relative "rails/version"
 require_relative "rails/configuration"
@@ -27,14 +26,25 @@ module Subflag
 
       # Configure Subflag for Rails
       #
-      # @example
+      # @example Using Subflag Cloud (SaaS)
       #   Subflag::Rails.configure do |config|
+      #     config.backend = :subflag
       #     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.plan }
       #     end
       #   end
       #
+      # @example Using ActiveRecord (self-hosted)
+      #   Subflag::Rails.configure do |config|
+      #     config.backend = :active_record
+      #   end
+      #
+      # @example Using Memory (testing)
+      #   Subflag::Rails.configure do |config|
+      #     config.backend = :memory
+      #   end
+      #
       # @yield [Configuration]
       def configure
         yield(configuration)
@@ -48,6 +58,16 @@ module Subflag
         @client ||= Client.new
       end
 
+      # Access the current provider instance
+      #
+      # Useful for the Memory backend where you can set flags directly:
+      #   Subflag::Rails.provider.set(:my_flag, true)
+      #
+      # @return [Object] The current OpenFeature provider
+      def provider
+        @provider
+      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.
@@ -72,21 +92,52 @@ module Subflag
       def reset!
         @configuration = Configuration.new
         @client = nil
+        @provider = nil
       end
 
       private
 
       def setup_provider
-        return unless configuration.api_key
+        @provider = build_provider
+        return unless @provider
 
-        provider = ::Subflag::Provider.new(
+        OpenFeature::SDK.configure do |config|
+          config.set_provider(@provider)
+        end
+      end
+
+      def build_provider
+        case configuration.backend
+        when :subflag
+          build_subflag_provider
+        when :active_record
+          build_active_record_provider
+        when :memory
+          build_memory_provider
+        else
+          raise ArgumentError, "Unknown backend: #{configuration.backend}. Use :subflag, :active_record, or :memory"
+        end
+      end
+
+      def build_subflag_provider
+        return nil unless configuration.api_key
+
+        require_relative "rails/backends/subflag_provider"
+        Backends::SubflagProvider.new(
           api_key: configuration.api_key,
           api_url: configuration.api_url
         )
+      end
 
-        OpenFeature::SDK.configure do |config|
-          config.set_provider(provider)
-        end
+      def build_active_record_provider
+        require_relative "rails/backends/active_record_provider"
+        require_relative "rails/models/flag"
+        Backends::ActiveRecordProvider.new
+      end
+
+      def build_memory_provider
+        require_relative "rails/backends/memory_provider"
+        Backends::MemoryProvider.new
       end
     end
   end

metadata

@@ -1,22 +1,22 @@
 --- !ruby/object:Gem::Specification
 name: subflag-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Subflag
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-08 00:00:00.000000000 Z
+date: 2025-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: subflag-openfeature-provider
+  name: openfeature-sdk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.1
+        version: '0.3'
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.0'
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.1
+        version: '0.3'
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.0'
@@ -170,9 +170,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
-description: Rails integration for Subflag feature flags. Get typed values (boolean,
-  string, integer, double, object) with user targeting. Includes generators, view
-  helpers, and ActiveRecord context integration.
+description: Feature flags for Rails with pluggable backends. Use Subflag Cloud (SaaS),
+  ActiveRecord (self-hosted), or Memory (testing). Get typed values (boolean, string,
+  integer, double, object) with the same API regardless of backend.
 email:
 - support@subflag.com
 executables: []
@@ -183,15 +183,20 @@ files:
 - LICENSE.txt
 - README.md
 - lib/generators/subflag/install_generator.rb
-- lib/generators/subflag/templates/initializer.rb
+- lib/generators/subflag/templates/create_subflag_flags.rb.tt
+- lib/generators/subflag/templates/initializer.rb.tt
 - lib/subflag-rails.rb
 - lib/subflag/rails.rb
+- lib/subflag/rails/backends/active_record_provider.rb
+- lib/subflag/rails/backends/memory_provider.rb
+- lib/subflag/rails/backends/subflag_provider.rb
 - lib/subflag/rails/client.rb
 - lib/subflag/rails/configuration.rb
 - lib/subflag/rails/context_builder.rb
 - lib/subflag/rails/evaluation_result.rb
 - lib/subflag/rails/flag_accessor.rb
 - lib/subflag/rails/helpers.rb
+- lib/subflag/rails/models/flag.rb
 - lib/subflag/rails/railtie.rb
 - lib/subflag/rails/request_cache.rb
 - lib/subflag/rails/test_helpers.rb