onni 0.1.0

data/lib/onni/adapters/memory.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Onni
+  module Adapters
+    class Memory
+      EMPTY_GATES = [].freeze
+
+      def initialize(lock: Sync.new_lock)
+        @features = {}
+        @gates = {}
+        @stats = {}
+        @lock = lock
+      end
+
+      def clear!
+        @lock.synchronize do
+          @features.clear
+          @gates.clear
+          @stats.clear
+        end
+      end
+
+      def add(key)
+        @lock.synchronize { @features[key.to_s] = true }
+      end
+
+      def exist?(key)
+        @lock.synchronize do
+          @features.key?(key.to_s) || @gates.fetch(key.to_s, []).any?
+        end
+      end
+
+      def feature_keys
+        @lock.synchronize do
+          (@features.keys + @gates.select { |_key, gates| gates.any? }.keys).uniq.sort
+        end
+      end
+
+      def gates_for(key)
+        @lock.synchronize { gates_for_unlocked(key.to_s) }
+      end
+
+      def gates_for_many(keys)
+        @lock.synchronize do
+          keys.each_with_object({}) do |key, loaded|
+            loaded[key.to_s] = gates_for_unlocked(key.to_s)
+          end
+        end
+      end
+
+      def replace_gates(key, gates)
+        @lock.synchronize { @gates[key.to_s] = gates.map { |gate| stringify(gate) } }
+      end
+
+      def add_gate(key, gate_key, value)
+        @lock.synchronize do
+          list = (@gates[key.to_s] ||= [])
+          entry = {"key" => gate_key.to_s, "value" => value.to_s}
+          list << entry unless list.any? { |gate| gate["key"] == entry["key"] && gate["value"] == entry["value"] }
+        end
+      end
+
+      def remove_gate(key, gate_key, value = nil)
+        @lock.synchronize do
+          list = @gates[key.to_s]
+          next if list.nil?
+
+          list.reject! do |gate|
+            gate["key"] == gate_key.to_s && (value.nil? || gate["value"] == value.to_s)
+          end
+        end
+      end
+
+      def clear_gates(key)
+        @lock.synchronize { @gates[key.to_s] = [] }
+      end
+
+      def record_stat(key, enabled:, weight: 1)
+        weight = weight.to_i.clamp(1, Stats::Sampler::MAX_WEIGHT)
+        @lock.synchronize do
+          bucket = (@stats[stat_bucket_key(key)] ||= {enabled: 0, disabled: 0})
+          bucket[enabled ? :enabled : :disabled] += weight
+        end
+      end
+
+      def record_stats_batch(buckets)
+        @lock.synchronize do
+          buckets.each do |feature_key, counts|
+            bucket = (@stats[stat_bucket_key(feature_key)] ||= {enabled: 0, disabled: 0})
+            bucket[:enabled] += counts[:enabled].to_i
+            bucket[:disabled] += counts[:disabled].to_i
+          end
+        end
+        buckets.size
+      end
+
+      def stats_for(key, period: "hour", from: 24.hours.ago, to: Time.current)
+        @lock.synchronize do
+          @stats.filter_map do |bucket_key, counts|
+            feature_key, period_start = bucket_key.split("|", 2)
+            next unless feature_key == key.to_s
+
+            started = Time.parse("#{period_start} UTC")
+            next unless started.between?(from, to)
+
+            {
+              "period_start" => started,
+              "period" => period,
+              "enabled_hits" => counts[:enabled],
+              "disabled_hits" => counts[:disabled]
+            }
+          end
+        end
+      end
+
+      def purge_stats_batch(older_than:, batch_size:, after_id: 0)
+        @lock.synchronize do
+          matching = @stats.keys.select { |bucket_key|
+            _feature_key, period_start = bucket_key.split("|", 2)
+            Time.parse("#{period_start} UTC") < older_than
+          }.sort
+          slice = matching.first(batch_size)
+          slice.each { |bucket_key| @stats.delete(bucket_key) }
+          return {deleted: 0, last_id: nil} if slice.empty?
+
+          {deleted: slice.size, last_id: (slice.size == batch_size) ? (after_id + slice.size) : nil}
+        end
+      end
+
+      def stats_overview
+        @lock.synchronize do
+          starts = @stats.keys.filter_map { |bucket_key|
+            _feature_key, period_start = bucket_key.split("|", 2)
+            Time.parse("#{period_start} UTC")
+          }
+          {
+            bucket_count: @stats.size,
+            oldest_period_start: starts.min
+          }
+        end
+      end
+
+      private
+
+      def gates_for_unlocked(key)
+        list = @gates[key]
+        return EMPTY_GATES if list.nil? || list.empty?
+
+        list.map(&:dup)
+      end
+
+      def stringify(gate)
+        {"key" => gate[:key] || gate["key"], "value" => (gate[:value] || gate["value"]).to_s}
+      end
+
+      def stat_bucket_key(key)
+        "#{key}|#{Time.now.utc.strftime("%Y-%m-%dT%H:00:00")}"
+      end
+    end
+  end
+end

data/lib/onni/conditions.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Onni
+  # YAML `conditions` narrow a rollout after a gate matches (audience targeting).
+  # They are not authorization. Supported entries:
+  # - group name registered via Onni.register_group
+  # - actor predicate method name ending in ? (for example beta_tester?)
+  module Conditions
+    module_function
+
+    def met?(name, actor, definition: nil)
+      definition ||= Registry.definition(name) || {}
+      conditions = Array(definition["conditions"])
+      return true if conditions.empty?
+      # Global checks (no actor) only answer whether a gate is armed.
+      return true if actor.nil?
+
+      conditions.all? { |condition| match?(condition, actor) }
+    end
+
+    def match?(condition, actor)
+      name = condition.to_s
+      return Group.member?(name, actor) if Group.known?(name)
+      return actor.public_send(name) if name.end_with?("?") && actor.respond_to?(name)
+
+      false
+    end
+    private_class_method :match?
+  end
+end

data/lib/onni/configuration.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/numeric/time"
+require "onni/stats/sampler"
+
+module Onni
+  class Configuration
+    CONCURRENCY_MODES = %i[mutex none].freeze
+
+    attr_accessor :features_path, :cache, :cache_ttl, :stats_enabled, :stats_retention,
+      :stats_sampler, :stats_ignore, :stats_scale_sampled_hits, :stats_buffer, :adapter, :admin_authorized
+    attr_reader :stats_sample_rate, :concurrency
+
+    def initialize
+      @features_path = nil
+      @cache = nil
+      @cache_ttl = 15 * 60
+      @stats_enabled = true
+      @stats_sample_rate = 1.0
+      # Optional callable `{name:, enabled:} -> rate|bool|nil` (nil falls back to stats_sample_rate).
+      @stats_sampler = nil
+      # Feature keys that never write hit buckets.
+      @stats_ignore = []
+      # When true, a kept sample increments by ~1/rate so totals estimate full traffic.
+      @stats_scale_sampled_hits = true
+      # When true, hit stats coalesce in the fiber-local buffer until Onni.flush_stats! / reset_request!.
+      @stats_buffer = false
+      # How long hourly hit buckets are kept. Used by Onni::Stats::Purge / the cleanup job.
+      @stats_retention = 90.days
+      # :mutex covers threads and fibers on Ruby 3.4+; :none skips locking.
+      @concurrency = :mutex
+      @adapter = :memory
+      # Who may open the Onni ActiveAdmin dashboard (not application authorization).
+      # Called with the ActiveAdmin page controller as receiver (instance_exec).
+      @admin_authorized = -> { true }
+    end
+
+    def stats_sample_rate=(value)
+      @stats_sample_rate = Stats::Sampler.coerce_rate(value)
+    end
+
+    def concurrency=(value)
+      mode = value.to_sym
+      unless CONCURRENCY_MODES.include?(mode)
+        raise ArgumentError, "Unknown Onni concurrency #{value.inspect} (expected #{CONCURRENCY_MODES.join(", ")})"
+      end
+
+      @concurrency = mode
+      Sync.reset! if defined?(Onni::Sync)
+      Onni.reset_adapter! if Onni.respond_to?(:reset_adapter!)
+    end
+  end
+end

data/lib/onni/engine.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+return unless defined?(Rails::Engine)
+
+module Onni
+  class Engine < ::Rails::Engine
+    engine_name "onni"
+
+    initializer "onni.configure", before: :load_config_initializers do
+      Onni.configure do |config|
+        config.features_path = Rails.root.join("config/features.yml")
+        config.cache = Rails.cache
+        config.adapter = Rails.env.test? ? :memory : :active_record
+      end
+    end
+
+    # Rails engines eager-load every app/* directory. ActiveAdmin DSL files are
+    # not Zeitwerk constants; ActiveAdmin loads them via load_paths.
+    initializer "onni.configure_zeitwerk" do
+      Rails.autoloaders.main.ignore(root.join("app/admin"))
+    end
+
+    initializer "onni.load_active_admin" do
+      next unless defined?(ActiveAdmin)
+
+      path = root.join("app/admin").to_s
+      ActiveSupport.on_load(:after_initialize) do
+        ActiveAdmin.application.load_paths << path unless ActiveAdmin.application.load_paths.include?(path)
+      end
+    end
+
+    initializer "onni.i18n" do
+      I18n.load_path += Dir[root.join("config/locales/*.yml")]
+    end
+
+    config.after_initialize do
+      boot_sync_registry!
+    end
+
+    def self.boot_sync_registry!
+      return unless Rails.env.local?
+      return if defined?(Rake) && Rake.application.top_level_tasks.any? { |task| task.start_with?("db:") }
+      return if Onni.configuration.adapter == :memory
+
+      Onni.sync_registry!
+    rescue ActiveRecord::StatementInvalid, ActiveRecord::NoDatabaseError
+      nil
+    end
+  end
+end

data/lib/onni/flag.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Onni
+  class Flag
+    attr_reader :name
+
+    def initialize(name)
+      @name = name.to_s
+    end
+
+    def exist?
+      Registry.known?(name)
+    end
+
+    def enabled?(actor = nil, record_stats: true)
+      Onni.enabled?(name, actor, record_stats: record_stats)
+    end
+
+    def gates
+      @gates ||= Onni.adapter.gates_for(name)
+    end
+
+    def definition
+      @definition ||= Registry.definition(name) || {}
+    end
+
+    def description
+      definition["description"]
+    end
+
+    def expires_at
+      definition["expires_at"]
+    end
+
+    def variants
+      raw = definition["variants"] || gates_variants
+      return {} if raw.blank?
+
+      raw.transform_keys(&:to_s).transform_values(&:to_i)
+    end
+
+    private
+
+    def gates_variants
+      gate = gates.find { |entry| entry["key"] == "variants" }
+      return {} unless gate
+
+      JSON.parse(gate["value"])
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/onni/group.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Onni
+  module Group
+    @registry = {}.freeze
+
+    module_function
+
+    def register(name, &block)
+      Sync.synchronize do
+        next_registry = @registry.dup
+        next_registry[name.to_sym] = block
+        @registry = next_registry
+      end
+    end
+
+    def clear!
+      Sync.synchronize { @registry = {} }
+    end
+
+    def names
+      Sync.synchronize { @registry.keys }
+    end
+
+    def known?(name)
+      Sync.synchronize { @registry.key?(name.to_sym) }
+    end
+
+    def member?(name, actor)
+      block = Sync.synchronize { @registry[name.to_sym] }
+      return false unless block
+
+      block.call(actor, name.to_sym)
+    end
+  end
+end

data/lib/onni/instrumenter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Onni
+  # Publishes ActiveSupport::Notifications with a `.onni` suffix
+  # (for example `stats.record.onni`).
+  module Instrumenter
+    module_function
+
+    def instrument(name, payload = {})
+      bus = notifications_bus
+      if bus
+        bus.instrument("#{name}.onni", payload) do |event_payload|
+          yield(event_payload) if block_given?
+        end
+      elsif block_given?
+        yield(payload)
+      end
+    end
+
+    def notifications_bus
+      return unless defined?(ActiveSupport::Notifications)
+
+      ActiveSupport::Notifications
+    end
+    private_class_method :notifications_bus
+  end
+end

data/lib/onni/migrator/importer.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Onni
+  module Migrator
+    # Copies gates from any source that exposes #feature_keys and #gates.
+    # Gate rows: feature_key, key, value (String or Symbol keys).
+    # Imports: boolean, actors, groups, percentage_of_actors, variants.
+    # Skips unknown registry keys and unsupported gate keys (counted in skipped_gates).
+    class Importer
+      SUPPORTED_GATE_KEYS = %w[boolean actors groups percentage_of_actors variants].freeze
+
+      def initialize(source)
+        @source = source
+      end
+
+      def call
+        features = 0
+        gates = 0
+        skipped_gates = 0
+
+        @source.feature_keys.each do |key|
+          next unless Registry.known?(key)
+
+          Onni.add(key)
+          features += 1
+        end
+
+        @source.gates.each do |row|
+          feature_key = gate_field(row, :feature_key)
+          gate_key = gate_field(row, :key).to_s
+          value = gate_field(row, :value)
+          next unless Registry.known?(feature_key)
+
+          unless SUPPORTED_GATE_KEYS.include?(gate_key)
+            skipped_gates += 1
+            next
+          end
+
+          Onni.add(feature_key)
+          Onni.adapter.add_gate(feature_key, gate_key, value)
+          Onni::Store.bust_cache!(feature_key)
+          gates += 1
+        end
+
+        {features: features, gates: gates, skipped_gates: skipped_gates}
+      end
+
+      private
+
+      def gate_field(row, name)
+        row[name] || row[name.to_s]
+      end
+    end
+  end
+end

data/lib/onni/migrator/snapshot.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Onni
+  module Migrator
+    # In-memory source for Onni.migrate!. Wrap rows from any prior feature-flag store.
+    class Snapshot
+      attr_reader :feature_keys, :gates
+
+      def initialize(feature_keys:, gates:)
+        @feature_keys = Array(feature_keys)
+        @gates = Array(gates)
+      end
+    end
+  end
+end

data/lib/onni/registry.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "time"
+require "yaml"
+
+module Onni
+  module Registry
+    module_function
+
+    def config
+      loaded = @config
+      return loaded if loaded
+
+      Sync.synchronize do
+        @config ||= load_config
+      end
+    end
+
+    def reload!
+      Sync.synchronize do
+        @config = nil
+      end
+      config
+    end
+
+    def known?(name)
+      config.key?(name.to_s)
+    end
+
+    def definition(name)
+      config[name.to_s]
+    end
+
+    def require_definition!(name)
+      definition(name) || raise_unknown!(name)
+    end
+
+    def raise_unknown!(name)
+      message = "Feature `#{name}` not found in features.yml"
+      if defined?(Rails)
+        Rails.logger.error(message)
+        ActionReporter.notify(message) if defined?(ActionReporter) && Rails.env.production?
+      end
+      raise KeyError, message
+    end
+
+    def load_config
+      path = Onni.configuration.features_path
+      path ||= default_features_path
+      return {} if path.nil? || !File.exist?(path)
+
+      raw = File.read(path)
+      loaded = YAML.safe_load(raw, aliases: true)
+      return {} unless loaded.is_a?(Hash)
+
+      loaded.each_value { |definition| attach_expiry!(definition) if definition.is_a?(Hash) }
+      loaded
+    end
+    private_class_method :load_config
+
+    def attach_expiry!(definition)
+      raw = definition["expires_at"]
+      return if raw.nil? || raw.to_s.empty?
+
+      definition["expires_at_time"] = Time.parse(raw.to_s).utc
+    rescue ArgumentError, TypeError
+      nil
+    end
+    private_class_method :attach_expiry!
+
+    def default_features_path
+      return unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+      Rails.root.join("config/features.yml")
+    end
+    private_class_method :default_features_path
+  end
+end

data/lib/onni/request_store.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Onni
+  # Fiber-local request scratch (gates preload, stats buffer).
+  # Hosts clear via Onni.reset_request! at request end.
+  module RequestStore
+    GATES_KEY = :onni_request_gates
+    STATS_KEY = :onni_stats_buffer
+
+    module_function
+
+    def gates
+      Fiber[GATES_KEY]
+    end
+
+    def gates=(value)
+      Fiber[GATES_KEY] = value
+    end
+
+    def stats_buffer
+      Fiber[STATS_KEY]
+    end
+
+    def stats_buffer=(value)
+      Fiber[STATS_KEY] = value
+    end
+
+    def clear!
+      Fiber[GATES_KEY] = nil
+      Fiber[STATS_KEY] = nil
+    end
+  end
+end

data/lib/onni/stats/buffer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Onni
+  module Stats
+    # Coalesces hit weights per feature until flush (request end / host job).
+    module Buffer
+      module_function
+
+      def add(name, enabled:, weight:)
+        buckets = RequestStore.stats_buffer || {}
+        key = name.to_s
+        bucket = (buckets[key] ||= {enabled: 0, disabled: 0})
+        bucket[enabled ? :enabled : :disabled] += weight.to_i
+        RequestStore.stats_buffer = buckets
+      end
+
+      def flush!
+        buckets = RequestStore.stats_buffer
+        RequestStore.stats_buffer = nil
+        return 0 if buckets.nil? || buckets.empty?
+
+        adapter = Onni.adapter
+        if adapter.respond_to?(:record_stats_batch)
+          adapter.record_stats_batch(buckets)
+        else
+          buckets.each do |feature_key, counts|
+            adapter.record_stat(feature_key, enabled: true, weight: counts[:enabled]) if counts[:enabled].positive?
+            adapter.record_stat(feature_key, enabled: false, weight: counts[:disabled]) if counts[:disabled].positive?
+          end
+        end
+        buckets.size
+      end
+    end
+  end
+end

data/lib/onni/stats/overview.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Onni
+  module Stats
+    # Operator-facing storage summary so retention and growth stay visible.
+    module Overview
+      ROW_WARNING = 1_000_000
+
+      module_function
+
+      def call
+        raw = Onni.adapter.stats_overview
+        retention = Onni.configuration.stats_retention
+        oldest = raw[:oldest_period_start]
+        past_retention =
+          if oldest && retention
+            oldest < retention.ago
+          else
+            false
+          end
+
+        {
+          bucket_count: raw[:bucket_count].to_i,
+          oldest_period_start: oldest,
+          retention: retention,
+          sample_rate: Onni.configuration.stats_sample_rate,
+          scale_sampled_hits: Onni.configuration.stats_scale_sampled_hits,
+          past_retention: past_retention,
+          large_table: raw[:bucket_count].to_i >= ROW_WARNING
+        }
+      end
+    end
+  end
+end