subflag-rails 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd3dfb04635e013ed8a9da2282150acf511c8704aace3c439a06f7e5dd0ac24a
-  data.tar.gz: adc804044699b6cea75d8b44fc742d08f2a96b24092a8e66d19b419f41c45fa1
+  metadata.gz: 474015cc849b73a4360fa11418161fbc78c6bbc163596b5b9add7e45929b6db4
+  data.tar.gz: 25f595010b6722d107b0604774ac089386e9d3ced39d7fef72411964a310140c
 SHA512:
-  metadata.gz: eb94613ee232272a8799ff0f7623c02d2d6e398ed0b7fbb231ff48bdf1e160ff99cb2110622567374012de4418e9b40129f7b14b0fabe7624904c399696f6dfc
-  data.tar.gz: 6327d0185659e82b95a922380cfbae030a42f91676a5a00d1a5fb43120c46eedd8d88432c0ec5cc7d20724494abd57be11ac6c47e2da26b536daa159174bf9ac
+  metadata.gz: afbe39727f8e70a3273b77e49bf8127debc459487b4d01bc14693c682082592b11fd3506388a8db2bd5021e9bbb914767e19f279a56a56a30c114fe79f10b0f2
+  data.tar.gz: f124c9b3103ff13453615be92dfe7639fabfeb042d514bc4232b5a73e8fa1dcbe812e4d0fb418c45a35c33ac0e71753958d37cff01c6742ff991a408e637946f

data/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.6.0] - 2025-12-15
+
+### Added
+
+- **Percentage rollouts for ActiveRecord backend**: Gradually roll out features to a percentage of users
+  - Deterministic assignment using MurmurHash3 (same user always gets the same result)
+  - Combine with segment conditions (e.g., "50% of pro users")
+  - Configure via Admin UI or targeting rules JSON
+- New dependency: `murmurhash3` gem for consistent hashing
+
+### Changed
+
+- `TargetingEngine.evaluate` now accepts optional `flag_key:` parameter (required for percentage rollouts)
+- Targeting rules validation now accepts `percentage` as alternative to `conditions`
+
+## [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)
-
-## Backends
+```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")
+```
 
-Choose where your flags live:
+Target different values to different users:
 
-| 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 |
+```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"
+```
+
+```bash
+rails generate subflag:install --backend=active_record
+rails db:migrate
+```
 
-# If using Subflag Cloud (backend: :subflag), also add:
-gem 'subflag-openfeature-provider'
+```ruby
+# config/routes.rb
+mount Subflag::Rails::Engine => "/subflag"
 ```
 
-### Option 1: Subflag Cloud (Default)
+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,7 +356,9 @@ 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 |
 |--------|------|-------------|
@@ -466,6 +482,18 @@ Subflag::Rails::Flag.create!(
 }
 ```
 
+**Percentage rollouts:**
+
+Gradually roll out features to a percentage of users using the Admin UI:
+
+1. Create or edit a flag at `/subflag`
+2. Add a targeting rule with a **percentage** (0-100)
+3. Optionally combine with conditions (e.g., "50% of pro users")
+
+Assignment is deterministic — the same user always gets the same result for the same flag.
+
+> **Note:** Percentage rollouts require `targeting_key` in your user context (typically the user ID).
+
 **How evaluation works:**
 
 1. Flag disabled? → return code default
@@ -486,6 +514,8 @@ Rails.application.routes.draw do
 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

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 %>

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

@@ -0,0 +1,241 @@
+<div class="flex justify-between items-center mb-10">
+  <h2 style="font-size: 20px;">Edit Flag: <span class="mono"><%= @flag.key %></span></h2>
+  <a href="<%= flags_path %>" class="btn">Back to Flags</a>
+</div>
+
+<div class="card">
+  <h2>Basic Settings</h2>
+  <%= render "form", flag: @flag %>
+</div>
+
+<div class="card">
+  <h2>Targeting Rules</h2>
+  <p class="text-muted mb-10">Rules are evaluated in order. First match wins. If no rules match, the default value is used.</p>
+
+  <div id="rules-container">
+    <!-- Rules rendered by JS -->
+  </div>
+
+  <button type="button" class="btn mt-10" onclick="addRule()">+ Add Rule</button>
+
+  <input type="hidden" name="targeting_rules_json" id="targeting-rules-json" value="<%= @flag.targeting_rules.to_json %>">
+
+  <div class="mt-10">
+    <button type="button" class="btn btn-primary" onclick="saveRules()">Save Rules</button>
+  </div>
+</div>
+
+<div class="card">
+  <h2>Test Rules</h2>
+  <p class="text-muted mb-10">Enter a context (JSON) to test which value would be returned.</p>
+
+  <%= form_with url: test_flag_path(@flag), method: :post, local: true do |f| %>
+    <div class="form-group">
+      <%= f.label :context, "Test Context (JSON)" %>
+      <%= f.text_area :context, rows: 4, placeholder: '{"email": "test@company.com", "role": "admin"}', value: @test_context&.to_json, class: "mono" %>
+    </div>
+    <%= f.submit "Test", class: "btn" %>
+  <% end %>
+
+  <% if defined?(@test_result) && @test_result %>
+    <div class="mt-10" style="padding: 15px; background: #f0f9ff; border: 1px solid #bae6fd; border-radius: 4px;">
+      <strong>Result:</strong> <span class="mono"><%= @test_result.inspect %></span>
+    </div>
+  <% end %>
+</div>
+
+<style>
+  .rule { border: 1px solid #ddd; border-radius: 4px; padding: 15px; margin-bottom: 10px; background: #fafafa; }
+  .rule-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 10px; }
+  .rule-value { display: flex; gap: 10px; align-items: center; margin-bottom: 10px; }
+  .rule-value input { width: 200px; }
+  .rule-logic { margin-bottom: 10px; }
+  .rule-logic label { margin-right: 15px; }
+  .condition { display: flex; gap: 8px; align-items: center; margin-bottom: 8px; }
+  .condition select, .condition input { padding: 6px 10px; border: 1px solid #ddd; border-radius: 4px; font-size: 13px; }
+  .condition input[type="text"] { width: 180px; }
+  .remove-btn { background: none; border: none; color: #dc3545; cursor: pointer; font-size: 18px; padding: 0 5px; }
+  .remove-btn:hover { color: #c82333; }
+</style>
+
+<script>
+  const OPERATORS = [
+    { value: "EQUALS", label: "equals" },
+    { value: "NOT_EQUALS", label: "not equals" },
+    { value: "IN", label: "in (comma-separated)" },
+    { value: "NOT_IN", label: "not in" },
+    { value: "CONTAINS", label: "contains" },
+    { value: "STARTS_WITH", label: "starts with" },
+    { value: "ENDS_WITH", label: "ends with" },
+    { value: "GREATER_THAN", label: ">" },
+    { value: "LESS_THAN", label: "<" },
+    { value: "MATCHES", label: "matches (regex)" }
+  ];
+
+  let rules = [];
+
+  function init() {
+    const saved = document.getElementById("targeting-rules-json").value;
+    if (saved) {
+      try {
+        rules = JSON.parse(saved) || [];
+      } catch (e) {
+        rules = [];
+      }
+    }
+    renderRules();
+  }
+
+  function renderRules() {
+    const container = document.getElementById("rules-container");
+    container.innerHTML = rules.map((rule, ruleIndex) => renderRule(rule, ruleIndex)).join("");
+  }
+
+  function renderRule(rule, ruleIndex) {
+    const conditions = rule.conditions?.conditions || [];
+    const logicType = rule.conditions?.type || "AND";
+
+    return `
+      <div class="rule" data-rule-index="${ruleIndex}">
+        <div class="rule-header">
+          <strong>Rule ${ruleIndex + 1}</strong>
+          <button type="button" class="remove-btn" onclick="removeRule(${ruleIndex})">&times;</button>
+        </div>
+        <div class="rule-value">
+          <label>Return value:</label>
+          <input type="text" value="${escapeHtml(rule.value || '')}" onchange="updateRuleValue(${ruleIndex}, this.value)" placeholder="value when matched">
+        </div>
+        <div class="rule-logic">
+          <label><input type="radio" name="logic-${ruleIndex}" value="AND" ${logicType === 'AND' ? 'checked' : ''} onchange="updateLogic(${ruleIndex}, 'AND')"> ALL match</label>
+          <label><input type="radio" name="logic-${ruleIndex}" value="OR" ${logicType === 'OR' ? 'checked' : ''} onchange="updateLogic(${ruleIndex}, 'OR')"> ANY match</label>
+        </div>
+        <div class="conditions" id="conditions-${ruleIndex}">
+          ${conditions.map((c, cIndex) => renderCondition(c, ruleIndex, cIndex)).join("")}
+        </div>
+        <button type="button" class="btn btn-sm" onclick="addCondition(${ruleIndex})">+ Add Condition</button>
+      </div>
+    `;
+  }
+
+  function renderCondition(condition, ruleIndex, condIndex) {
+    const operatorOptions = OPERATORS.map(op =>
+      `<option value="${op.value}" ${condition.operator === op.value ? 'selected' : ''}>${op.label}</option>`
+    ).join("");
+
+    const valueDisplay = Array.isArray(condition.value) ? condition.value.join(", ") : (condition.value || "");
+
+    return `
+      <div class="condition">
+        <input type="text" placeholder="attribute" value="${escapeHtml(condition.attribute || '')}" onchange="updateCondition(${ruleIndex}, ${condIndex}, 'attribute', this.value)">
+        <select onchange="updateCondition(${ruleIndex}, ${condIndex}, 'operator', this.value)">
+          ${operatorOptions}
+        </select>
+        <input type="text" placeholder="value" value="${escapeHtml(valueDisplay)}" onchange="updateCondition(${ruleIndex}, ${condIndex}, 'value', this.value)">
+        <button type="button" class="remove-btn" onclick="removeCondition(${ruleIndex}, ${condIndex})">&times;</button>
+      </div>
+    `;
+  }
+
+  function addRule() {
+    rules.push({
+      value: "",
+      conditions: { type: "AND", conditions: [{ attribute: "", operator: "EQUALS", value: "" }] }
+    });
+    renderRules();
+  }
+
+  function removeRule(index) {
+    rules.splice(index, 1);
+    renderRules();
+  }
+
+  function updateRuleValue(ruleIndex, value) {
+    rules[ruleIndex].value = value;
+  }
+
+  function updateLogic(ruleIndex, type) {
+    rules[ruleIndex].conditions.type = type;
+  }
+
+  function addCondition(ruleIndex) {
+    if (!rules[ruleIndex].conditions.conditions) {
+      rules[ruleIndex].conditions.conditions = [];
+    }
+    rules[ruleIndex].conditions.conditions.push({ attribute: "", operator: "EQUALS", value: "" });
+    renderRules();
+  }
+
+  function removeCondition(ruleIndex, condIndex) {
+    rules[ruleIndex].conditions.conditions.splice(condIndex, 1);
+    renderRules();
+  }
+
+  function updateCondition(ruleIndex, condIndex, field, value) {
+    const cond = rules[ruleIndex].conditions.conditions[condIndex];
+    if (field === "value" && (cond.operator === "IN" || cond.operator === "NOT_IN")) {
+      cond.value = value.split(",").map(v => v.trim());
+    } else {
+      cond[field] = value;
+    }
+  }
+
+  function saveRules() {
+    const form = document.createElement("form");
+    form.method = "POST";
+    form.action = "<%= flag_path(@flag) %>";
+
+    const methodInput = document.createElement("input");
+    methodInput.type = "hidden";
+    methodInput.name = "_method";
+    methodInput.value = "PATCH";
+    form.appendChild(methodInput);
+
+    const csrfInput = document.createElement("input");
+    csrfInput.type = "hidden";
+    csrfInput.name = "<%= request_forgery_protection_token %>";
+    csrfInput.value = "<%= form_authenticity_token %>";
+    form.appendChild(csrfInput);
+
+    // Send all flag params to preserve other fields
+    const keyInput = document.createElement("input");
+    keyInput.type = "hidden";
+    keyInput.name = "flag[key]";
+    keyInput.value = "<%= @flag.key %>";
+    form.appendChild(keyInput);
+
+    const valueInput = document.createElement("input");
+    valueInput.type = "hidden";
+    valueInput.name = "flag[value]";
+    valueInput.value = "<%= @flag.value %>";
+    form.appendChild(valueInput);
+
+    const typeInput = document.createElement("input");
+    typeInput.type = "hidden";
+    typeInput.name = "flag[value_type]";
+    typeInput.value = "<%= @flag.value_type %>";
+    form.appendChild(typeInput);
+
+    const enabledInput = document.createElement("input");
+    enabledInput.type = "hidden";
+    enabledInput.name = "flag[enabled]";
+    enabledInput.value = "<%= @flag.enabled? %>";
+    form.appendChild(enabledInput);
+
+    const rulesInput = document.createElement("input");
+    rulesInput.type = "hidden";
+    rulesInput.name = "flag[targeting_rules]";
+    rulesInput.value = JSON.stringify(rules);
+    form.appendChild(rulesInput);
+
+    document.body.appendChild(form);
+    form.submit();
+  }
+
+  function escapeHtml(str) {
+    const div = document.createElement("div");
+    div.textContent = str;
+    return div.innerHTML;
+  }
+
+  document.addEventListener("DOMContentLoaded", init);
+</script>

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

@@ -0,0 +1,50 @@
+<div class="flex justify-between items-center mb-10">
+  <h2 style="font-size: 20px;">Feature Flags</h2>
+  <a href="<%= new_flag_path %>" class="btn btn-primary">New Flag</a>
+</div>
+
+<div class="card">
+  <% if @flags.any? %>
+    <table>
+      <thead>
+        <tr>
+          <th>Key</th>
+          <th>Type</th>
+          <th>Default Value</th>
+          <th>Status</th>
+          <th>Rules</th>
+          <th></th>
+        </tr>
+      </thead>
+      <tbody>
+        <% @flags.each do |flag| %>
+          <tr>
+            <td class="mono"><%= flag.key %></td>
+            <td><%= flag.value_type %></td>
+            <td class="mono"><%= truncate(flag.value.to_s, length: 30) %></td>
+            <td>
+              <% if flag.enabled? %>
+                <span class="badge badge-success">enabled</span>
+              <% else %>
+                <span class="badge badge-secondary">disabled</span>
+              <% end %>
+            </td>
+            <td>
+              <% rules_count = flag.targeting_rules&.size || 0 %>
+              <span class="text-muted"><%= rules_count %> rule<%= rules_count == 1 ? '' : 's' %></span>
+            </td>
+            <td>
+              <div class="actions">
+                <a href="<%= edit_flag_path(flag) %>" class="btn btn-sm">Edit</a>
+                <%= button_to flag.enabled? ? "Disable" : "Enable", toggle_flag_path(flag), method: :post, class: "btn btn-sm" %>
+                <%= button_to "Delete", flag_path(flag), method: :delete, class: "btn btn-sm btn-danger", data: { confirm: "Delete flag '#{flag.key}'?" } %>
+              </div>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% else %>
+    <p class="text-muted">No flags yet. <a href="<%= new_flag_path %>">Create your first flag</a>.</p>
+  <% end %>
+</div>

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

@@ -0,0 +1,5 @@
+<h2 style="font-size: 20px; margin-bottom: 20px;">New Flag</h2>
+
+<div class="card">
+  <%= render "form", flag: @flag %>
+</div>

data/config/routes.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+Subflag::Rails::Engine.routes.draw do
+  resources :flags do
+    member do
+      post :toggle
+      post :test
+    end
+  end
+
+  root to: "flags#index"
+end

data/lib/subflag/rails/models/flag.rb

@@ -70,7 +70,7 @@ module Subflag
       def evaluate(context: nil, expected_type: nil)
         rules = parsed_targeting_rules
         raw_value = if rules.present? && context.present?
-                      matched = TargetingEngine.evaluate(rules, context)
+                      matched = TargetingEngine.evaluate(rules, context, flag_key: key)
                       matched || value
                     else
                       value
@@ -146,7 +146,20 @@ module Subflag
 
           rule = rule.transform_keys(&:to_s)
           errors.add(:targeting_rules, "rule #{index} must have a 'value' key") unless rule.key?("value")
-          errors.add(:targeting_rules, "rule #{index} must have a 'conditions' key") unless rule.key?("conditions")
+
+          has_conditions = rule.key?("conditions") && rule["conditions"].present?
+          has_percentage = rule.key?("percentage")
+
+          unless has_conditions || has_percentage
+            errors.add(:targeting_rules, "rule #{index} must have 'conditions' and/or 'percentage'")
+          end
+
+          if has_percentage
+            pct = rule["percentage"]
+            unless pct.is_a?(Numeric) && pct >= 0 && pct <= 100
+              errors.add(:targeting_rules, "rule #{index} percentage must be a number between 0 and 100")
+            end
+          end
         end
       end
     end

data/lib/subflag/rails/targeting_engine.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "murmurhash3"
+
 module Subflag
   module Rails
     # Evaluates targeting rules against evaluation contexts.
@@ -34,25 +36,56 @@ module Subflag
         #
         # @param rules [Array<Hash>, nil] Array of targeting rules with values
         # @param context [Hash, nil] Evaluation context with attributes
+        # @param flag_key [String, nil] The flag key (required for percentage rollouts)
         # @return [String, nil] The matched rule's value, or nil if no match
-        def evaluate(rules, context)
+        def evaluate(rules, context, flag_key: nil)
           return nil if rules.nil? || rules.empty?
           return nil if context.nil? || context.empty?
 
-          # Normalize context keys to strings for comparison
           normalized_context = normalize_context(context)
+          targeting_key = extract_targeting_key(normalized_context)
 
           rules.each do |rule|
             rule = rule.transform_keys(&:to_s)
             conditions = rule["conditions"]
-            next unless conditions
+            percentage = rule["percentage"]
+
+            segment_matches = if conditions.nil? || conditions.empty?
+                                true
+                              else
+                                evaluate_rule(conditions, normalized_context)
+                              end
+
+            next unless segment_matches
 
-            if evaluate_rule(conditions, normalized_context)
-              return rule["value"]
+            if percentage
+              next unless targeting_key && flag_key
+              next unless evaluate_percentage(targeting_key, flag_key, percentage)
             end
+
+            return rule["value"]
           end
 
-          nil # No rules matched
+          nil
+        end
+
+        # Evaluate percentage rollout using MurmurHash3
+        #
+        # @param targeting_key [String] Unique identifier for the context
+        # @param flag_key [String] The flag being evaluated
+        # @param percentage [Integer] Target percentage (0-100)
+        # @return [Boolean] true if context falls within percentage
+        def evaluate_percentage(targeting_key, flag_key, percentage)
+          percentage = percentage.to_i
+          return false if percentage <= 0
+          return true if percentage >= 100
+
+          hash_input = "#{targeting_key}:#{flag_key}"
+          hash_bytes = MurmurHash3::V128.str_hash(hash_input)
+          hash_code = [hash_bytes[0]].pack("L").unpack1("l")
+          bucket = hash_code.abs % 100
+
+          bucket < percentage
         end
 
         private
@@ -63,6 +96,10 @@ module Subflag
           end
         end
 
+        def extract_targeting_key(context)
+          context["targeting_key"] || context["targetingKey"]
+        end
+
         # Evaluate an AND/OR rule block
         def evaluate_rule(rule, context)
           rule = rule.transform_keys(&:to_s)

data/lib/subflag/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Subflag
   module Rails
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: subflag-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Subflag
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-11 00:00:00.000000000 Z
+date: 2025-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openfeature-sdk
@@ -58,6 +58,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: murmurhash3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.6
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -170,7 +184,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
-description: Feature flags for Rails with pluggable backends. Use Subflag Cloud (SaaS),
+description: Feature flags for Rails with selectable 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:
@@ -182,6 +196,14 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- app/controllers/subflag/rails/application_controller.rb
+- app/controllers/subflag/rails/flags_controller.rb
+- app/views/layouts/subflag/rails/application.html.erb
+- app/views/subflag/rails/flags/_form.html.erb
+- app/views/subflag/rails/flags/edit.html.erb
+- app/views/subflag/rails/flags/index.html.erb
+- app/views/subflag/rails/flags/new.html.erb
+- config/routes.rb
 - lib/generators/subflag/install_generator.rb
 - lib/generators/subflag/templates/create_subflag_flags.rb.tt
 - lib/generators/subflag/templates/initializer.rb.tt