onni 0.1.0

data/app/models/onni/stat_bucket.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Onni
+  class StatBucket < ::ActiveRecord::Base
+    self.table_name = "onni_feature_stat_buckets"
+
+    belongs_to :feature, class_name: "Onni::Feature", foreign_key: :feature_key,
+      primary_key: :key, inverse_of: :stat_buckets, optional: true
+
+    validates :feature_key, :period, :period_start, presence: true
+  end
+end

data/app/views/admin/features/_chart.html.erb

@@ -0,0 +1,24 @@
+<figure class="my-4">
+  <figcaption>
+    <svg width="28" height="12" aria-hidden="true"><line x1="0" y1="6" x2="28" y2="6" stroke="#2563eb" stroke-width="3" /></svg>
+    Enabled
+    <svg width="28" height="12" aria-hidden="true"><line x1="0" y1="6" x2="28" y2="6" stroke="#c2410c" stroke-width="3" stroke-dasharray="6 4" /></svg>
+    Disabled
+    <p>Scale: 0 to <%= number_with_delimiter(chart.maximum) %> evaluations per <%= chart.hourly? ? "hour" : "day" %>.</p>
+  </figcaption>
+  <svg viewBox="40 8 752 216" width="100%" height="220" preserveAspectRatio="none" role="img" aria-labelledby="onni-hit-chart-title onni-hit-chart-description">
+    <title id="onni-hit-chart-title">Enabled and disabled evaluations over time</title>
+    <desc id="onni-hit-chart-description">A solid blue line shows enabled evaluations and a dashed orange line shows disabled evaluations. Exact counts are available in the table below.</desc>
+    <% [24, 116, 208].each do |y| %>
+      <line x1="56" y1="<%= y %>" x2="776" y2="<%= y %>" stroke="currentColor" stroke-opacity="0.2" vector-effect="non-scaling-stroke" />
+    <% end %>
+    <polyline points="<%= chart.points("enabled_hits") %>" fill="none" stroke="#2563eb" stroke-width="3" vector-effect="non-scaling-stroke" />
+    <polyline points="<%= chart.points("disabled_hits") %>" fill="none" stroke="#c2410c" stroke-width="3" stroke-dasharray="6 4" vector-effect="non-scaling-stroke" />
+  </svg>
+  <p>
+    <%= l(chart.hourly? ? chart.rows.first.fetch("period_start") : chart.rows.first.fetch("period_start").to_date, format: :short) %>
+    to
+    <%= l(chart.hourly? ? chart.rows.last.fetch("period_start") : chart.rows.last.fetch("period_start").to_date, format: :short) %>
+    (UTC)
+  </p>
+</figure>

data/app/views/admin/features/_stats.html.erb

@@ -0,0 +1,49 @@
+<section aria-labelledby="onni-hit-history" class="mb-6">
+  <h3 id="onni-hit-history" class="font-semibold mb-2">Hits</h3>
+  <%= form_with url: admin_features_feature_path, method: :get, local: true, class: "mb-4" do %>
+    <%= hidden_field_tag :key, flag.name %>
+    <%= label_tag :range, "History" %>
+    <%= select_tag :range, options_for_select([["Last 24 hours", "24h"], ["Last 7 days", "7d"], ["Last 30 days", "30d"]], chart.range) %>
+    <%= submit_tag "Show history", name: nil, class: "button" %>
+  <% end %>
+
+  <dl class="mb-4">
+    <dt>Enabled evaluations</dt>
+    <dd data-onni-enabled-hits><%= number_with_delimiter(chart.enabled_hits) %></dd>
+    <dt>Disabled evaluations</dt>
+    <dd data-onni-disabled-hits><%= number_with_delimiter(chart.disabled_hits) %></dd>
+    <dt>Enabled share</dt>
+    <dd data-onni-enabled-percentage><%= chart.enabled_percentage ? number_to_percentage(chart.enabled_percentage, precision: 1) : "No data" %></dd>
+  </dl>
+  <p>Counts reflect feature evaluations, not unique users. Sampling can affect these counts: they may include estimates or only sampled evaluations.</p>
+
+  <% if chart.enabled_percentage.nil? %>
+    <p role="status" class="my-4">No recorded evaluations in this window. Choose a longer window or check whether statistics collection is enabled.</p>
+  <% else %>
+    <%= render partial: "admin/features/chart", locals: { chart: chart } %>
+  <% end %>
+
+  <p>Times are UTC. The current <%= chart.hourly? ? "hour" : "day" %> is incomplete. Periods without recorded evaluations are shown as zero; older history may have been removed.</p>
+  <details class="mt-4">
+    <summary>View evaluation counts</summary>
+    <table>
+      <caption>Recorded evaluations by <%= chart.hourly? ? "hour" : "day" %> (UTC)</caption>
+      <thead>
+        <tr>
+          <th scope="col"><%= chart.hourly? ? "Hour" : "Day" %> (UTC)</th>
+          <th scope="col">Enabled</th>
+          <th scope="col">Disabled</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% chart.rows.each do |row| %>
+          <tr>
+            <th scope="row"><%= l(chart.hourly? ? row.fetch("period_start") : row.fetch("period_start").to_date, format: :short) %></th>
+            <td><%= number_with_delimiter(row.fetch("enabled_hits")) %></td>
+            <td><%= number_with_delimiter(row.fetch("disabled_hits")) %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </details>
+</section>

data/app/views/admin/features/show.html.erb

@@ -0,0 +1,60 @@
+<% flag = @flag %>
+<% variants = flag.variants %>
+<div class="p-4">
+  <h2 class="text-xl font-semibold mb-2"><%= flag.name %></h2>
+  <p class="mb-4"><%= flag.description %></p>
+  <p class="mb-4">Expires: <%= flag.expires_at || "—" %></p>
+  <p class="mb-4">
+    Hit sample rate:
+    <% if !Onni.configuration.stats_enabled %>
+      off
+    <% elsif Array(Onni.configuration.stats_ignore).any? { |key| key.to_s == flag.name } %>
+      ignored
+    <% else %>
+      <%= Onni.configuration.stats_sample_rate %>
+      <% if Onni.configuration.stats_sampler %>
+        (global default; per-flag sampler may override)
+      <% end %>
+    <% end %>
+  </p>
+
+  <h3 class="font-semibold mb-2">Gates</h3>
+  <ul class="mb-4 list-disc pl-5">
+    <% flag.gates.each do |gate| %>
+      <li><code><%= gate["key"] %></code> = <code><%= gate["value"] %></code></li>
+    <% end %>
+    <% if flag.gates.empty? %>
+      <li>No gates (disabled)</li>
+    <% end %>
+  </ul>
+
+  <%= form_with url: admin_features_update_feature_path(key: flag.name), method: :post, local: true, class: "mb-6 space-y-3" do %>
+    <div>
+      <label>Percentage of actors (0-100)</label>
+      <%= number_field_tag :percentage, flag.gates.find { |gate| gate["key"] == "percentage_of_actors" }&.fetch("value", nil), min: 0, max: 100 %>
+    </div>
+    <div>
+      <label>Enable group</label>
+      <%= select_tag :group_name, options_for_select(Onni::Group.names), include_blank: true %>
+      <%= select_tag :group_action, options_for_select([%w[Enable enable], %w[Disable disable]]), include_blank: "Group action" %>
+    </div>
+    <div>
+      <label>A/B variants (name and weight)</label>
+      <div class="flex gap-2 items-end">
+        <div>
+          <label for="variant_control">control</label>
+          <%= number_field_tag "variants[control]", variants["control"], min: 0, max: 100, id: "variant_control" %>
+        </div>
+        <div>
+          <label for="variant_treatment">treatment</label>
+          <%= number_field_tag "variants[treatment]", variants["treatment"], min: 0, max: 100, id: "variant_treatment" %>
+        </div>
+      </div>
+    </div>
+    <%= submit_tag "Save", class: "button" %>
+  <% end %>
+
+  <%= render partial: "admin/features/stats", locals: { chart: @hit_chart, flag: flag } %>
+
+  <p class="mt-4"><%= link_to "Back to features", admin_features_path %></p>
+</div>

data/config/locales/en.yml

@@ -0,0 +1,6 @@
+en:
+  onni:
+    menu: Features
+  active_admin:
+    features:
+      menu: Features

data/config/polyrun_coverage.yml

@@ -0,0 +1,8 @@
+track_under:
+  - lib
+  - app
+minimum_line_percent: 50
+report_formats:
+  - html
+  - cobertura
+  - console

data/lib/generators/onni/install_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module Onni
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        next_number = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        if Dir.exist?(dirname)
+          while Dir.children(dirname).any? { |name| name.start_with?(next_number) }
+            next_number = (next_number.to_i + 1).to_s
+          end
+        end
+        next_number
+      end
+
+      def copy_migration
+        migration_template "create_onni_features.rb.tt",
+          "db/migrate/create_onni_features.rb"
+      end
+
+      def create_features_yml
+        template "features.yml.tt", "config/features.yml"
+      end
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/onni.rb"
+      end
+    end
+  end
+end

data/lib/generators/onni/stats_cleanup_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module Onni
+  module Generators
+    class StatsCleanupGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        next_number = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        if Dir.exist?(dirname)
+          while Dir.children(dirname).any? { |name| name.start_with?(next_number) }
+            next_number = (next_number.to_i + 1).to_s
+          end
+        end
+        next_number
+      end
+
+      def create_job
+        template "purge_stats_job.rb.tt", "app/jobs/onni_purge_stats_job.rb"
+      end
+
+      def create_period_start_index_migration
+        migration_template "add_onni_stats_period_start_index.rb.tt",
+          "db/migrate/add_onni_stats_period_start_index.rb"
+      end
+
+      def show_schedule_notes
+        say <<~MSG
+
+          Onni stats cleanup installed.
+
+          1. Migrate: bin/rails db:migrate
+          2. Set retention in config/initializers/onni.rb:
+               config.stats_retention = 90.days
+          3. Schedule the job daily (host job backend or cron), for example:
+               OnniPurgeStatsJob.perform_later
+          4. One-shot console drain (no queue):
+               Onni.purge_stats!(older_than: 90.days.ago)
+
+          See README "Stats growth and cleanup" for >1GB / >10M row guidance.
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/onni/templates/add_onni_stats_period_start_index.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class AddOnniStatsPeriodStartIndex < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_index :onni_feature_stat_buckets, :period_start,
+      name: "index_onni_feature_stats_on_period_start",
+      if_not_exists: true
+  end
+end

data/lib/generators/onni/templates/create_onni_features.rb.tt

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class CreateOnniFeatures < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :onni_features do |t|
+      t.string :key, null: false
+      t.timestamps
+    end
+    add_index :onni_features, :key, unique: true
+
+    create_table :onni_feature_gates do |t|
+      t.string :feature_key, null: false
+      t.string :key, null: false
+      t.text :value, null: false
+      t.timestamps
+    end
+    add_index :onni_feature_gates, [:feature_key, :key, :value],
+      unique: true, name: "index_onni_feature_gates_unique"
+
+    create_table :onni_feature_stat_buckets do |t|
+      t.string :feature_key, null: false
+      t.string :period, null: false, default: "hour"
+      t.datetime :period_start, null: false
+      t.bigint :enabled_hits, null: false, default: 0
+      t.bigint :disabled_hits, null: false, default: 0
+      t.timestamps
+    end
+    add_index :onni_feature_stat_buckets, [:feature_key, :period, :period_start],
+      unique: true, name: "index_onni_feature_stats_unique"
+    add_index :onni_feature_stat_buckets, :period_start,
+      name: "index_onni_feature_stats_on_period_start"
+  end
+end
+

data/lib/generators/onni/templates/features.yml.tt

@@ -0,0 +1,9 @@
+---
+# new_checkout:
+#   expires_at: "2027-01-01"
+#   description: "Checkout redesign experiment"
+#   variants:
+#     control: 50
+#     treatment: 50
+#
+# Do not use Onni flags as authorization. Keep access control in your policy layer.

data/lib/generators/onni/templates/initializer.rb.tt

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+Onni.configure do |config|
+  config.features_path = Rails.root.join("config/features.yml")
+  config.cache = Rails.cache
+  config.cache_ttl = 15.minutes
+  config.stats_enabled = true
+  config.stats_sample_rate = 1.0 # float 0.0..1.0 (clamped); 1.0 skips Random
+  config.stats_scale_sampled_hits = true # kept samples increment by ~1/rate
+  # config.stats_buffer = true # coalesce hits until Onni.reset_request! / flush_stats!
+  # config.stats_ignore = %w[health_probe_flag]
+  # config.stats_sampler = ->(ctx) { ctx[:name] == "busy_flag" ? 0.01 : nil }
+  config.stats_retention = 90.days
+  # Per request: Onni.preload! then Onni.reset_request! in middleware / around_action
+  # :mutex (default) is safe across threads and fibers on Ruby 3.4+; :none skips locks.
+  config.concurrency = :mutex
+  config.adapter = Rails.env.test? ? :memory : :active_record
+  # Who may open the Onni ActiveAdmin dashboard (not app authorization):
+  # config.admin_authorized = -> { current_admin_user&.can_manage_experiments? }
+end
+
+# Hit-bucket cleanup (install job with: bin/rails generate onni:stats_cleanup)
+# Schedule daily, e.g. OnniPurgeStatsJob.perform_later
+# Or drain in console: Onni.purge_stats!(older_than: 90.days.ago)
+
+# Audience targeting for rollouts — not access control.
+Onni.register_group(:beta_testers) do |actor, _|
+  actor.respond_to?(:beta_tester?) && actor.beta_tester?
+end
+
+# One-time import from another feature-flag library (safe to re-run; skips unknown YAML keys
+# and unsupported gates). Pass any source with #feature_keys and #gates, e.g. Migrator::Snapshot:
+# Onni.migrate!(Onni::Migrator::Snapshot.new(feature_keys: [...], gates: [...]))
+
+# Optional explicit ActiveAdmin support:
+# require "onni/active_admin"
+
+# Optional ops subscribe (ActiveSupport::Notifications):
+# ActiveSupport::Notifications.subscribe(/\.onni$/) do |event|
+#   Rails.logger.info([event.name, event.payload].inspect)
+# end

data/lib/generators/onni/templates/purge_stats_job.rb.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Deletes Onni hourly hit buckets older than config.stats_retention (or older_than).
+# Schedule daily. Console drain without a queue: Onni.purge_stats!(older_than: 90.days.ago)
+class OnniPurgeStatsJob < ApplicationJob
+  queue_as :low
+
+  def perform(older_than: nil, batch_size: 1_000, after_id: 0, processed_count: 0)
+    cutoff = older_than.present? ? Time.iso8601(older_than) : nil
+
+    Onni::Stats::Purge.call(
+      older_than: cutoff,
+      batch_size: batch_size,
+      after_id: after_id,
+      processed_count: processed_count,
+      enqueue: ->(**kwargs) {
+        self.class.perform_later(
+          older_than: kwargs[:older_than].iso8601,
+          batch_size: kwargs[:batch_size],
+          after_id: kwargs[:after_id],
+          processed_count: kwargs[:processed_count]
+        )
+      }
+    )
+  end
+end

data/lib/onni/active_admin.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# First-class ActiveAdmin support for Onni.
+# The Rails engine loads `app/admin` when ActiveAdmin is already defined.
+# Require this file explicitly when you want to assert ActiveAdmin is present:
+#
+#   require "onni/active_admin"
+#
+require "onni"
+
+raise LoadError, "ActiveAdmin is required for onni/active_admin" unless defined?(ActiveAdmin)
+
+require "onni/engine" if defined?(Rails::Engine)

data/lib/onni/actor.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Onni
+  module Actor
+    module_function
+
+    def id(actor)
+      return if actor.nil?
+      return actor.feature_actor_id if actor.respond_to?(:feature_actor_id)
+
+      "#{actor.class.name};#{actor.id}"
+    end
+
+    def percentage_value(actor, feature_key)
+      raw = id(actor).to_s
+      Zlib.crc32("#{feature_key}:#{raw}") % 100
+    end
+
+    def variant_for(actor, feature_key, variants)
+      return if actor.nil? || variants.blank?
+
+      score = percentage_value(actor, feature_key)
+      cursor = 0
+      variants.each do |name, weight|
+        cursor += weight.to_i
+        return name.to_sym if score < cursor
+      end
+      variants.keys.last&.to_sym
+    end
+  end
+end

data/lib/onni/adapters/active_record.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Onni
+  module Adapters
+    class ActiveRecord
+      def add(key)
+        ::Onni::Feature.find_or_create_by!(key: key.to_s)
+      end
+
+      def exist?(key)
+        ::Onni::Feature.where(key: key.to_s).exists? ||
+          ::Onni::Gate.where(feature_key: key.to_s).exists?
+      end
+
+      def feature_keys
+        (
+          ::Onni::Feature.pluck(:key) +
+            ::Onni::Gate.distinct.pluck(:feature_key)
+        ).uniq.sort
+      end
+
+      def gates_for(key)
+        ::Onni::Gate.where(feature_key: key.to_s).map { |gate| {"key" => gate.key, "value" => gate.value} }
+      end
+
+      def gates_for_many(keys)
+        keys = keys.map(&:to_s)
+        grouped = ::Onni::Gate.where(feature_key: keys).group_by(&:feature_key)
+        keys.each_with_object({}) do |key, loaded|
+          loaded[key] = Array(grouped[key]).map { |gate| {"key" => gate.key, "value" => gate.value} }
+        end
+      end
+
+      def replace_gates(key, gates)
+        ::Onni::Gate.transaction do
+          ::Onni::Gate.where(feature_key: key.to_s).delete_all
+          gates.each { |gate| add_gate(key, gate[:key] || gate["key"], gate[:value] || gate["value"]) }
+        end
+      end
+
+      def add_gate(key, gate_key, value)
+        ::Onni::Gate.find_or_create_by!(feature_key: key.to_s, key: gate_key.to_s, value: value.to_s)
+      end
+
+      def remove_gate(key, gate_key, value = nil)
+        scope = ::Onni::Gate.where(feature_key: key.to_s, key: gate_key.to_s)
+        scope = scope.where(value: value.to_s) unless value.nil?
+        scope.delete_all
+      end
+
+      def clear_gates(key)
+        ::Onni::Gate.where(feature_key: key.to_s).delete_all
+      end
+
+      def record_stat(key, enabled:, weight: 1)
+        weight = weight.to_i.clamp(1, Stats::Sampler::MAX_WEIGHT)
+        upsert_stat_row(key.to_s, enabled: enabled, weight: weight)
+      end
+
+      def record_stats_batch(buckets)
+        ::Onni::StatBucket.transaction do
+          buckets.each do |feature_key, counts|
+            enabled_weight = counts[:enabled].to_i
+            disabled_weight = counts[:disabled].to_i
+            upsert_stat_row(feature_key, enabled: true, weight: enabled_weight) if enabled_weight.positive?
+            upsert_stat_row(feature_key, enabled: false, weight: disabled_weight) if disabled_weight.positive?
+          end
+        end
+        buckets.size
+      end
+
+      def stats_for(key, period: "hour", from: 24.hours.ago, to: Time.current)
+        ::Onni::StatBucket.where(feature_key: key.to_s, period: period, period_start: from..to)
+          .order(:period_start).map do |bucket|
+          {
+            "period_start" => bucket.period_start,
+            "period" => bucket.period,
+            "enabled_hits" => bucket.enabled_hits,
+            "disabled_hits" => bucket.disabled_hits
+          }
+        end
+      end
+
+      def purge_stats_batch(older_than:, batch_size:, after_id: 0)
+        ids = ::Onni::StatBucket
+          .where(period_start: ...older_than)
+          .where("id > ?", after_id)
+          .order(:id)
+          .limit(batch_size)
+          .pluck(:id)
+        return {deleted: 0, last_id: nil} if ids.empty?
+
+        deleted = ::Onni::StatBucket.where(id: ids).delete_all
+        {deleted: deleted, last_id: ids.last}
+      end
+
+      def stats_overview
+        {
+          bucket_count: ::Onni::StatBucket.count,
+          oldest_period_start: ::Onni::StatBucket.minimum(:period_start)
+        }
+      end
+
+      private
+
+      def upsert_stat_row(key, enabled:, weight:)
+        weight = weight.to_i.clamp(1, Stats::Sampler::MAX_WEIGHT)
+        period_start = Time.current.utc.beginning_of_hour
+        now = Time.current
+        column = enabled ? "enabled_hits" : "disabled_hits"
+        # Intent: column conflict target matches index_onni_feature_stats_unique (SQLite + PostgreSQL ON CONFLICT).
+        ::Onni::StatBucket.upsert(
+          {
+            feature_key: key.to_s,
+            period: "hour",
+            period_start: period_start,
+            enabled_hits: enabled ? weight : 0,
+            disabled_hits: enabled ? 0 : weight,
+            created_at: now,
+            updated_at: now
+          },
+          unique_by: %i[feature_key period period_start],
+          on_duplicate: ::Arel.sql("#{column} = #{column} + #{weight}, updated_at = excluded.updated_at")
+        )
+      end
+    end
+  end
+end