subflag-rails 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da40f567a605d55076aaeabed1edd404bb41ba2a1703c56595e42611ebf4aaa4
-  data.tar.gz: 39df667c30500ebf560e90694213f05b479d60f488575c7f2503409bc640222d
+  metadata.gz: 56034c2de3a47fbbb96f97aa9f1149c87c58bc1558b50a7520db7b07a93c3e85
+  data.tar.gz: dc818a9034753adfa51b2cd810a5affe7c3cb9e30ff9943c67e0df01d0c6cf66
 SHA512:
-  metadata.gz: 0bb2499ecf945fb2586918f5c3e57cdda5e6ce2f143eb4b6d1d674370412ccee6f6e8fe5d992705ac4b0b28de88465ebe7e140fad1a2c71f691982ebe363c4ce
-  data.tar.gz: f255c179b502557624bfcfc81bc06743c13898bef9d7b5225e4519e097fbdfc7b88af2b2729088883747cb3a123f1a51fff521618527e68e7e77ca494212be32
+  metadata.gz: ca26926074b168811199ae8fe3e065843073dcbae20667a9951a641bfb0e02e0d30e11ed16ae7376a1cf75c5f8ffc46e8012929494ba7d142a80260732ee4e0c
+  data.tar.gz: c8b0af027aa0cf5d01bdac26b2a7681c05fa818bfe2a92d1d178a3c8cd67cc0d94f555b495b132593009c2272ad3b3b60b61b6b93087109321c99bffdef446a3

data/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.1] - 2025-12-15
+
+### Fixed
+
+- **Admin UI not loading**: Include `app/` and `config/` directories in gem package
+  - Previously only `lib/` was packaged, causing mounted Engine to fail
+
+## [0.5.0] - 2025-12-11
+
+### Added
+
+- **Admin UI**: Mount at `/subflag` to manage flags visually
+  - List, create, edit, and delete flags
+  - Toggle flags enabled/disabled
+  - Visual targeting rule builder (no JSON editing required)
+  - Test rules against sample contexts
+  - Configurable authentication via `config.admin_auth`
+- **Targeting rules for ActiveRecord backend**: Return different values based on user attributes
+  - 12 comparison operators: EQUALS, NOT_EQUALS, IN, NOT_IN, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, MATCHES
+  - AND/OR condition groups
+  - First-match evaluation order
+- **TargetingEngine**: Evaluates rules against user context
+
+### Changed
+
+- `subflag_flags` table now includes `targeting_rules` column (JSON/JSONB)
+- Generator creates migration with JSONB for PostgreSQL, JSON for other databases
+
+## [0.4.0] - 2025-12-09
+
+### Added
+
+- **Selectable backends**: Choose where flags are stored
+  - `:subflag` - Subflag Cloud (default)
+  - `:active_record` - Self-hosted, flags in your database
+  - `:memory` - In-memory for testing
+- **ActiveRecord backend**: Store flags in `subflag_flags` table
+- **Memory backend**: Programmatic flag management for tests
+- Generator `--backend` option to configure storage
+
 ## [0.3.0] - 2025-12-07
 
 ### Added

data/README.md

@@ -1,41 +1,72 @@
 # Subflag Rails
 
-Typed feature flags for Rails. Booleans, strings, numbers, and JSON — with pluggable backends.
+Feature flags that return strings, numbers, JSON — not just booleans.
 
-[Subflag](https://subflag.com)
+```ruby
+limit = subflag_value(:upload_limit_mb, default: 10)
+tier_config = subflag_value(:pricing_tiers, default: { basic: 5, pro: 50 })
+welcome = subflag_value(:welcome_message, default: "Hello")
+```
 
-## Backends
+Target different values to different users:
 
-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 |
+```ruby
+# config/initializers/subflag.rb
+Subflag::Rails.configure do |config|
+  config.backend = :active_record
 
-**Same API regardless of backend:**
+  config.user_context do |user|
+    { targeting_key: user.id.to_s, plan: user.plan, email: user.email }
+  end
+end
+```
 
 ```ruby
-subflag_enabled?(:new_checkout)           # Works with any backend
-subflag_value(:max_projects, default: 3)  # Works with any backend
+# Premium users get 100, free users get 10
+subflag_value(:max_projects, default: 10)
 ```
 
-## Installation
+Self-hosted or cloud. Same API.
 
-Add to your Gemfile:
+## Quick Start
 
 ```ruby
-gem 'subflag-rails'
+gem "subflag-rails"
+```
 
-# If using Subflag Cloud (backend: :subflag), also add:
-gem 'subflag-openfeature-provider'
+```bash
+rails generate subflag:install --backend=active_record
+rails db:migrate
 ```
 
-### Option 1: Subflag Cloud (Default)
+```ruby
+# config/routes.rb
+mount Subflag::Rails::Engine => "/subflag"
+```
+
+No external dependencies. Admin UI included.
+
+---
+
+## Backends
+
+Choose where your flags live:
+
+| Backend | Use Case | Flags Stored In |
+|---------|----------|-----------------|
+| `:active_record` | Self-hosted, no external dependencies, [built-in admin UI](#admin-ui-activerecord) | Your database |
+| `:subflag` | Dashboard, environments, percentage rollouts | [Subflag Cloud](https://subflag.com) |
+| `:memory` | Testing and development | In-memory hash |
+
+### Subflag Cloud
 
 Dashboard, environments, percentage rollouts, and user targeting.
 
+```ruby
+gem "subflag-rails"
+gem "subflag-openfeature-provider"
+```
+
 ```bash
 rails generate subflag:install
 ```
@@ -53,24 +84,7 @@ 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)
+### Memory (Testing)
 
 In-memory flags for tests and local development.
 
@@ -342,15 +356,18 @@ end
 
 ### ActiveRecord Flag Model
 
-When using `backend: :active_record`, flags are stored in the `subflag_flags` table:
+> **Note:** This section only applies when using `backend: :active_record`. For Subflag Cloud, manage flags in the [dashboard](https://app.subflag.com).
+
+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` | 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
@@ -363,6 +380,152 @@ Subflag::Rails::Flag.enabled.find_each { |f| puts "#{f.key}: #{f.typed_value}" }
 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
+```
+
+![Subflag Admin UI](https://raw.githubusercontent.com/subflag/sdk/main/packages/subflag-rails/docs/admin-ui.png)
+
+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:

data/app/controllers/subflag/rails/application_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    class ApplicationController < ActionController::Base
+      include ActionController::Flash
+
+      protect_from_forgery with: :exception
+
+      before_action :authenticate_admin!
+
+      private
+
+      def authenticate_admin!
+        auth_callback = Subflag::Rails.configuration.admin_auth_callback
+        return unless auth_callback
+
+        instance_exec(&auth_callback)
+      end
+    end
+  end
+end

data/app/controllers/subflag/rails/flags_controller.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    class FlagsController < ApplicationController
+      before_action :set_flag, only: %i[show edit update destroy toggle test]
+
+      def index
+        @flags = Flag.order(:key)
+      end
+
+      def show; end
+
+      def new
+        @flag = Flag.new(enabled: true, value_type: "boolean", value: "false")
+      end
+
+      def create
+        @flag = Flag.new(flag_params)
+        if @flag.save
+          redirect_to flags_path, notice: "Flag created."
+        else
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def edit; end
+
+      def update
+        if @flag.update(flag_params)
+          redirect_to edit_flag_path(@flag), notice: "Flag updated."
+        else
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      def destroy
+        @flag.destroy
+        redirect_to flags_path, notice: "Flag deleted."
+      end
+
+      def toggle
+        @flag.update!(enabled: !@flag.enabled)
+        redirect_to flags_path, notice: "Flag #{@flag.enabled? ? 'enabled' : 'disabled'}."
+      end
+
+      def test
+        context = parse_test_context(params[:context])
+        @test_result = @flag.evaluate(context: context)
+        @test_context = context
+
+        respond_to do |format|
+          format.html { render :edit }
+          format.json { render json: { result: @test_result, context: @test_context } }
+        end
+      end
+
+      private
+
+      def set_flag
+        @flag = Flag.find(params[:id])
+      end
+
+      def flag_params
+        params.require(:flag).permit(:key, :value, :value_type, :enabled, :description).tap do |p|
+          if params[:flag][:targeting_rules].present?
+            p[:targeting_rules] = JSON.parse(params[:flag][:targeting_rules])
+          else
+            p[:targeting_rules] = []
+          end
+        end
+      rescue JSON::ParserError
+        params.require(:flag).permit(:key, :value, :value_type, :enabled, :description, :targeting_rules)
+      end
+
+      def parse_test_context(context_json)
+        return {} if context_json.blank?
+
+        JSON.parse(context_json).transform_keys(&:to_sym)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/app/views/layouts/subflag/rails/application.html.erb

@@ -0,0 +1,72 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Subflag Admin</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <%= csrf_meta_tags %>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #f5f5f5; color: #333; line-height: 1.5; }
+    a { color: #0066cc; text-decoration: none; }
+    a:hover { text-decoration: underline; }
+
+    .container { max-width: 900px; margin: 0 auto; padding: 20px; }
+    .header { background: #fff; border-bottom: 1px solid #ddd; padding: 15px 20px; margin-bottom: 20px; }
+    .header h1 { font-size: 18px; font-weight: 600; }
+    .header a { color: #333; }
+
+    .card { background: #fff; border: 1px solid #ddd; border-radius: 4px; padding: 20px; margin-bottom: 20px; }
+    .card h2 { font-size: 16px; margin-bottom: 15px; padding-bottom: 10px; border-bottom: 1px solid #eee; }
+
+    .notice { background: #d4edda; border: 1px solid #c3e6cb; color: #155724; padding: 10px 15px; border-radius: 4px; margin-bottom: 20px; }
+    .alert { background: #f8d7da; border: 1px solid #f5c6cb; color: #721c24; padding: 10px 15px; border-radius: 4px; margin-bottom: 20px; }
+    .errors { background: #f8d7da; border: 1px solid #f5c6cb; color: #721c24; padding: 10px 15px; border-radius: 4px; margin-bottom: 20px; }
+    .errors ul { margin-left: 20px; }
+
+    table { width: 100%; border-collapse: collapse; }
+    th, td { text-align: left; padding: 10px; border-bottom: 1px solid #eee; }
+    th { font-weight: 600; color: #666; font-size: 12px; text-transform: uppercase; }
+
+    .btn { display: inline-block; padding: 8px 16px; border: 1px solid #ddd; border-radius: 4px; background: #fff; color: #333; cursor: pointer; font-size: 14px; }
+    .btn:hover { background: #f5f5f5; text-decoration: none; }
+    .btn-primary { background: #0066cc; border-color: #0066cc; color: #fff; }
+    .btn-primary:hover { background: #0055aa; }
+    .btn-danger { background: #dc3545; border-color: #dc3545; color: #fff; }
+    .btn-danger:hover { background: #c82333; }
+    .btn-sm { padding: 4px 10px; font-size: 12px; }
+
+    .form-group { margin-bottom: 15px; }
+    .form-group label { display: block; margin-bottom: 5px; font-weight: 500; font-size: 14px; }
+    .form-group input, .form-group select, .form-group textarea { width: 100%; padding: 8px 12px; border: 1px solid #ddd; border-radius: 4px; font-size: 14px; }
+    .form-group input:focus, .form-group select:focus, .form-group textarea:focus { outline: none; border-color: #0066cc; }
+    .form-group small { color: #666; font-size: 12px; display: block; margin-top: 4px; }
+
+    .badge { display: inline-block; padding: 2px 8px; border-radius: 10px; font-size: 11px; font-weight: 600; }
+    .badge-success { background: #d4edda; color: #155724; }
+    .badge-secondary { background: #e9ecef; color: #6c757d; }
+
+    .actions { display: flex; gap: 8px; }
+    .mono { font-family: monospace; font-size: 13px; }
+    .text-muted { color: #666; }
+    .mt-10 { margin-top: 10px; }
+    .mb-10 { margin-bottom: 10px; }
+    .flex { display: flex; }
+    .justify-between { justify-content: space-between; }
+    .items-center { align-items: center; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <div class="container flex justify-between items-center" style="padding: 0;">
+      <h1><a href="<%= main_app.root_path rescue flags_path %>">Subflag</a></h1>
+      <a href="<%= flags_path %>">Flags</a>
+    </div>
+  </div>
+
+  <div class="container">
+    <% if flash[:notice] %><div class="notice"><%= flash[:notice] %></div><% end %>
+    <% if flash[:alert] %><div class="alert"><%= flash[:alert] %></div><% end %>
+    <%= yield %>
+  </div>
+</body>
+</html>

data/app/views/subflag/rails/flags/_form.html.erb

@@ -0,0 +1,45 @@
+<% if flag.errors.any? %>
+  <div class="errors">
+    <strong><%= pluralize(flag.errors.count, "error") %>:</strong>
+    <ul>
+      <% flag.errors.full_messages.each do |msg| %>
+        <li><%= msg %></li>
+      <% end %>
+    </ul>
+  </div>
+<% end %>
+
+<%= form_with model: flag, url: flag.persisted? ? flag_path(flag) : flags_path, local: true do |f| %>
+  <div class="form-group">
+    <%= f.label :key %>
+    <%= f.text_field :key, placeholder: "my-feature-flag", disabled: flag.persisted? %>
+    <small>Lowercase letters, numbers, and dashes only. Cannot be changed after creation.</small>
+  </div>
+
+  <div class="form-group">
+    <%= f.label :value_type, "Type" %>
+    <%= f.select :value_type, [["Boolean", "boolean"], ["String", "string"], ["Integer", "integer"], ["Float", "float"], ["Object (JSON)", "object"]], {}, disabled: flag.persisted? %>
+    <small>Cannot be changed after creation.</small>
+  </div>
+
+  <div class="form-group">
+    <%= f.label :value, "Default Value" %>
+    <%= f.text_field :value, placeholder: flag.value_type == "boolean" ? "true or false" : "default value" %>
+    <small>The value returned when no targeting rules match.</small>
+  </div>
+
+  <div class="form-group">
+    <%= f.label :description %>
+    <%= f.text_area :description, rows: 2, placeholder: "Optional description..." %>
+  </div>
+
+  <div class="form-group">
+    <%= f.label :enabled %>
+    <%= f.check_box :enabled %> Flag is enabled
+  </div>
+
+  <div class="mt-10">
+    <%= f.submit flag.persisted? ? "Update Flag" : "Create Flag", class: "btn btn-primary" %>
+    <a href="<%= flags_path %>" class="btn">Cancel</a>
+  </div>
+<% end %>