subflag-rails 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d5585ee53dcf0c1864f3d9bf5845a41cd8e3c884fe11ca457bc51b3ded8cfcd
-  data.tar.gz: 1014353a80ee041027dd501aea4035f7043b873dbf75506678e2852b948f436a
+  metadata.gz: bd3dfb04635e013ed8a9da2282150acf511c8704aace3c439a06f7e5dd0ac24a
+  data.tar.gz: adc804044699b6cea75d8b44fc742d08f2a96b24092a8e66d19b419f41c45fa1
 SHA512:
-  metadata.gz: 7a0b5adb5b8df94ed4e07ba41e47b4430b719b2cf741695b6f9029239aefa6437535d36fb08d9b2f12d84911126cdfa45d15429b2c024f0d93c694f6ee5e77e8
-  data.tar.gz: 582032e633830bb9e5867ae6883545a4ba5fd0ece16556a542f9de3513a5c0853f4ce7a121ad4af3d3ea6bc901ff136abc9f77f12eaa37789d64fa77bd11a750
+  metadata.gz: eb94613ee232272a8799ff0f7623c02d2d6e398ed0b7fbb231ff48bdf1e160ff99cb2110622567374012de4418e9b40129f7b14b0fabe7624904c399696f6dfc
+  data.tar.gz: 6327d0185659e82b95a922380cfbae030a42f91676a5a00d1a5fb43120c46eedd8d88432c0ec5cc7d20724494abd57be11ac6c47e2da26b536daa159174bf9ac

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, [built-in admin UI](#admin-ui-activerecord) | 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,217 @@ 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 | Default value (what everyone gets) |
+| `value_type` | string | Type: `boolean`, `string`, `integer`, `float`, `object` |
+| `enabled` | boolean | Whether the flag is active (default: true) |
+| `description` | text | Optional description |
+| `targeting_rules` | json | Optional rules for showing different values to different users |
+
+```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)
+```
+
+### Targeting Rules (ActiveRecord)
+
+Show different flag values to different users based on their attributes. Perfect for internal testing before wider rollout.
+
+> **Tip:** Use the [Admin UI](#admin-ui-activerecord) to manage targeting rules visually instead of editing JSON.
+
+**First, configure user context:**
+
+```ruby
+# config/initializers/subflag.rb
+Subflag::Rails.configure do |config|
+  config.backend = :active_record
+
+  config.user_context do |user|
+    {
+      targeting_key: user.id.to_s,
+      email: user.email,
+      role: user.role,           # e.g., "admin", "developer", "qa"
+      plan: user.plan            # e.g., "free", "pro", "enterprise"
+    }
+  end
+end
+```
+
+**Create flags with targeting rules:**
+
+```ruby
+# Internal team sees new feature, everyone else sees old
+Subflag::Rails::Flag.create!(
+  key: "new-dashboard",
+  value: "false",                    # Default: everyone gets false
+  value_type: "boolean",
+  targeting_rules: [
+    {
+      "value" => "true",             # Internal team gets true
+      "conditions" => {
+        "type" => "OR",
+        "conditions" => [
+          { "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@yourcompany.com" },
+          { "attribute" => "role", "operator" => "IN", "value" => ["admin", "developer", "qa"] }
+        ]
+      }
+    }
+  ]
+)
+```
+
+**Progressive rollout with multiple rules (first match wins):**
+
+```ruby
+Subflag::Rails::Flag.create!(
+  key: "max-projects",
+  value: "5",                        # Default: everyone gets 5
+  value_type: "integer",
+  targeting_rules: [
+    { "value" => "1000", "conditions" => { "type" => "AND", "conditions" => [{ "attribute" => "role", "operator" => "EQUALS", "value" => "admin" }] } },
+    { "value" => "100", "conditions" => { "type" => "AND", "conditions" => [{ "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@yourcompany.com" }] } },
+    { "value" => "25", "conditions" => { "type" => "AND", "conditions" => [{ "attribute" => "plan", "operator" => "EQUALS", "value" => "pro" }] } }
+  ]
+)
+```
+
+**Supported operators:**
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| `EQUALS` | `{ "attribute" => "role", "operator" => "EQUALS", "value" => "admin" }` | Exact match |
+| `NOT_EQUALS` | `{ "attribute" => "env", "operator" => "NOT_EQUALS", "value" => "prod" }` | Not equal |
+| `IN` | `{ "attribute" => "role", "operator" => "IN", "value" => ["admin", "qa"] }` | Value in list |
+| `NOT_IN` | `{ "attribute" => "country", "operator" => "NOT_IN", "value" => ["RU", "CN"] }` | Value not in list |
+| `CONTAINS` | `{ "attribute" => "email", "operator" => "CONTAINS", "value" => "test" }` | String contains |
+| `NOT_CONTAINS` | `{ "attribute" => "email", "operator" => "NOT_CONTAINS", "value" => "spam" }` | String doesn't contain |
+| `STARTS_WITH` | `{ "attribute" => "user_id", "operator" => "STARTS_WITH", "value" => "test-" }` | String prefix |
+| `ENDS_WITH` | `{ "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@company.com" }` | String suffix |
+| `GREATER_THAN` | `{ "attribute" => "age", "operator" => "GREATER_THAN", "value" => 18 }` | Numeric greater than |
+| `LESS_THAN` | `{ "attribute" => "items", "operator" => "LESS_THAN", "value" => 100 }` | Numeric less than |
+| `GREATER_THAN_OR_EQUAL` | `{ "attribute" => "score", "operator" => "GREATER_THAN_OR_EQUAL", "value" => 80 }` | Numeric greater or equal |
+| `LESS_THAN_OR_EQUAL` | `{ "attribute" => "score", "operator" => "LESS_THAN_OR_EQUAL", "value" => 50 }` | Numeric less or equal |
+| `MATCHES` | `{ "attribute" => "email", "operator" => "MATCHES", "value" => ".*@company\\.com$" }` | Regex match |
+
+**Combining conditions:**
+
+```ruby
+# OR: any condition matches
+{
+  "type" => "OR",
+  "conditions" => [
+    { "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@company.com" },
+    { "attribute" => "role", "operator" => "EQUALS", "value" => "admin" }
+  ]
+}
+
+# AND: all conditions must match
+{
+  "type" => "AND",
+  "conditions" => [
+    { "attribute" => "plan", "operator" => "EQUALS", "value" => "enterprise" },
+    { "attribute" => "country", "operator" => "IN", "value" => ["US", "CA"] }
+  ]
+}
+```
+
+**How evaluation works:**
+
+1. Flag disabled? → return code default
+2. For each rule (in order): if context matches → return rule's value
+3. No rules matched? → return flag's default `value`
+
+This lets you progressively widen access by adding rules, without changing existing ones.
+
+### Admin UI (ActiveRecord)
+
+Mount the admin UI to manage flags and targeting rules visually:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount Subflag::Rails::Engine => "/subflag"
+  # ... your other routes
+end
+```
+
+The admin UI provides:
+- List, create, edit, and delete flags
+- Toggle flags enabled/disabled
+- Visual targeting rule builder (no JSON editing)
+- Test rules against sample contexts
+
+**Secure the admin UI:**
+
+```ruby
+# config/initializers/subflag.rb
+Subflag::Rails.configure do |config|
+  config.backend = :active_record
+
+  # Require authentication for admin UI
+  config.admin_auth do
+    redirect_to main_app.root_path unless current_user&.admin?
+  end
+end
+```
+
+Visit `/subflag` in your browser to access the admin UI.
+
+## 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,121 @@ 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
+
+      # Helper for templates to detect PostgreSQL adapter
+      def postgresql?
+        return false unless defined?(::ActiveRecord::Base)
+
+        adapter = ::ActiveRecord::Base.connection_db_config.adapter.to_s rescue nil
+        adapter&.include?("postgresql") || adapter&.include?("postgis")
+      end
 
       def create_initializer
-        template "initializer.rb", "config/initializers/subflag.rb"
+        template "initializer.rb.tt", "config/initializers/subflag.rb"
+      end
+
+      def create_flags_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,22 @@
+# 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
+
+      # Targeting rules for showing different values to different users
+      # Stores an array of { value, conditions } rules as JSON
+      # First matching rule wins; falls back to `value` if no match
+      t.<%= postgresql? ? 'jsonb' : 'json' %> :targeting_rules
+
+      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)