onni 0.1.0

data/lib/onni/stats/purge.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Onni
+  module Stats
+    # Deletes hourly hit buckets older than a cutoff, in id-ordered batches.
+    # With enqueue, one batch runs then the next page is scheduled.
+    # Without enqueue (console `Purge.call`), remaining pages drain in-process.
+    class Purge
+      DEFAULT_BATCH_SIZE = 1_000
+
+      def self.call(**kwargs)
+        new(**kwargs).call
+      end
+
+      def initialize(older_than: nil, batch_size: DEFAULT_BATCH_SIZE, after_id: 0, processed_count: 0, enqueue: nil)
+        @older_than = older_than
+        @batch_size = batch_size
+        @after_id = after_id
+        @processed_count = processed_count
+        @enqueue = enqueue
+      end
+
+      def call
+        older_than = resolve_older_than
+        processed = @processed_count
+        after_id = @after_id
+
+        loop do
+          batch = Onni.adapter.purge_stats_batch(
+            older_than: older_than,
+            batch_size: @batch_size,
+            after_id: after_id
+          )
+          processed += batch[:deleted]
+          break if batch[:last_id].nil?
+
+          if @enqueue
+            @enqueue.call(
+              older_than: older_than,
+              batch_size: @batch_size,
+              after_id: batch[:last_id],
+              processed_count: processed
+            )
+            return {
+              deleted: processed - @processed_count,
+              processed_count: processed,
+              after_id: batch[:last_id],
+              continued: true
+            }
+          end
+
+          after_id = batch[:last_id]
+        end
+
+        {
+          deleted: processed - @processed_count,
+          processed_count: processed,
+          after_id: after_id,
+          continued: false
+        }
+      end
+
+      private
+
+      def resolve_older_than
+        return @older_than if @older_than
+
+        retention = Onni.configuration.stats_retention
+        if retention.nil?
+          raise ArgumentError, "Pass older_than: or set Onni.configuration.stats_retention"
+        end
+
+        retention.ago
+      end
+    end
+  end
+end

data/lib/onni/stats/sampler.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Onni
+  module Stats
+    # Sampling decision for hit stats:
+    # - float rate in 0.0..1.0 with clamp
+    # - skip Random when rate is 1.0
+    # - optional per-evaluation sampler callable
+    # - ignore list for noisy keys
+    # - optional inverse-rate weight so stored counters estimate full traffic
+    module Sampler
+      MAX_WEIGHT = 1_000_000
+
+      module_function
+
+      def decide(name:, enabled:)
+        config = Onni.configuration
+        return :skip unless config.stats_enabled
+        return :skip if ignored?(name, config)
+
+        rate = coerce_rate(rate_for(name: name, enabled: enabled, config: config))
+        return :skip if rate <= 0.0
+        return {record: true, weight: 1} if rate >= 1.0
+        return :skip unless Random.rand < rate
+
+        weight = config.stats_scale_sampled_hits ? weight_for(rate) : 1
+        {record: true, weight: weight}
+      end
+
+      def coerce_rate(rate)
+        case rate
+        when true then 1.0
+        when false, nil then 0.0
+        else
+          value = rate.to_f
+          value.clamp(0.0, 1.0)
+        end
+      end
+
+      def weight_for(rate)
+        return 1 if rate <= 0.0
+
+        (1.0 / rate).round.clamp(1, MAX_WEIGHT)
+      end
+
+      def rate_for(name:, enabled:, config:)
+        if config.stats_sampler
+          sampled = config.stats_sampler.call({name: name.to_s, enabled: enabled})
+          return sampled unless sampled.nil?
+        end
+
+        config.stats_sample_rate
+      end
+      private_class_method :rate_for
+
+      def ignored?(name, config)
+        Array(config.stats_ignore).any? { |key| key.to_s == name.to_s }
+      end
+      private_class_method :ignored?
+    end
+  end
+end

data/lib/onni/stats.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "onni/stats/purge"
+require "onni/stats/sampler"
+require "onni/stats/overview"
+require "onni/stats/buffer"
+
+module Onni
+  module Stats
+    module_function
+
+    def record(name, enabled:)
+      decision = Sampler.decide(name: name, enabled: enabled)
+      return if decision == :skip
+
+      Instrumenter.instrument("stats.record", name: name.to_s, enabled: enabled, weight: decision[:weight]) do
+        if Onni.configuration.stats_buffer
+          Buffer.add(name, enabled: enabled, weight: decision[:weight])
+        else
+          Onni.adapter.record_stat(name, enabled: enabled, weight: decision[:weight])
+        end
+      end
+    rescue => error
+      Rails.logger.warn("Onni stats failed: #{error.class}: #{error.message}") if defined?(Rails)
+    end
+
+    def for(name, period: "hour", from: 24.hours.ago, to: Time.current)
+      Onni.adapter.stats_for(name, period: period, from: from, to: to)
+    end
+
+    def purge!(**kwargs)
+      Instrumenter.instrument("stats.purge") do |payload|
+        result = Purge.call(**kwargs)
+        payload[:deleted] = result[:deleted]
+        payload[:processed_count] = result[:processed_count]
+        payload[:continued] = result[:continued]
+        result
+      end
+    end
+
+    def overview
+      Overview.call
+    end
+  end
+end

data/lib/onni/store.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "time"
+require "json"
+
+module Onni
+  module Store
+    CACHE_KEY_PREFIX = "onni/gates/"
+
+    module_function
+
+    def enabled?(name, actor = nil, record_stats: true)
+      return false unless Registry.known?(name)
+
+      result = evaluate(name, actor)
+      Stats.record(name, enabled: result) if record_stats
+      result
+    end
+
+    def variant(name, actor, record_stats: true)
+      return unless Registry.known?(name)
+      return if actor.nil?
+
+      definition = Registry.definition(name) || {}
+      return if expired?(definition)
+
+      gates = cached_gates(name)
+      return if gates.empty?
+
+      matched =
+        boolean_enabled?(gates) ||
+        actor_enabled?(gates, actor) ||
+        group_enabled?(gates, actor) ||
+        percentage_enabled?(gates, name, actor)
+      return unless matched
+      return unless Conditions.met?(name, actor, definition: definition)
+
+      Stats.record(name, enabled: true) if record_stats
+
+      variants = variant_weights(definition, gates)
+      return if variants.blank?
+
+      Actor.variant_for(actor, name, variants)
+    end
+
+    def evaluate(name, actor)
+      definition = Registry.definition(name) || {}
+      return false if expired?(definition)
+
+      gates = cached_gates(name)
+      return false if gates.empty?
+
+      matched =
+        boolean_enabled?(gates) ||
+        actor_enabled?(gates, actor) ||
+        group_enabled?(gates, actor) ||
+        percentage_enabled?(gates, name, actor)
+      return false unless matched
+
+      Conditions.met?(name, actor, definition: definition)
+    end
+    private_class_method :evaluate
+
+    def variant_weights(definition, gates)
+      raw = definition["variants"]
+      return normalize_variants(raw) if raw.present?
+
+      gate = Array(gates).find { |entry| entry["key"] == "variants" }
+      return {} unless gate
+
+      normalize_variants(JSON.parse(gate["value"]))
+    rescue JSON::ParserError
+      {}
+    end
+    private_class_method :variant_weights
+
+    def normalize_variants(raw)
+      raw.transform_keys(&:to_s).transform_values(&:to_i)
+    end
+    private_class_method :normalize_variants
+
+    def expired?(definition)
+      raw = definition["expires_at"]
+      return false if raw.nil? || raw.to_s.empty?
+
+      deadline = definition["expires_at_time"]
+      if deadline.nil?
+        begin
+          deadline = Time.parse(raw.to_s).utc
+        rescue ArgumentError, TypeError
+          return true
+        end
+      end
+      deadline < Time.now.utc
+    rescue ArgumentError, TypeError
+      true
+    end
+    private_class_method :expired?
+
+    def cached_gates(name)
+      key = name.to_s
+      preloaded = RequestStore.gates
+      return preloaded[key] if preloaded&.key?(key)
+
+      cache = Onni.configuration.cache
+      return Onni.adapter.gates_for(key) unless cache
+
+      cache.fetch(cache_key(key), expires_in: Onni.configuration.cache_ttl) do
+        Onni.adapter.gates_for(key)
+      end
+    end
+    private_class_method :cached_gates
+
+    def bust_cache!(name)
+      key = name.to_s
+      Onni.configuration.cache&.delete(cache_key(key))
+      RequestStore.gates&.delete(key)
+    end
+
+    def cache_key(name)
+      "#{CACHE_KEY_PREFIX}#{Onni.adapter.object_id}/#{name}"
+    end
+    private_class_method :cache_key
+
+    def boolean_enabled?(gates)
+      gates.any? { |gate| gate["key"] == "boolean" && gate["value"] == "true" }
+    end
+    private_class_method :boolean_enabled?
+
+    def actor_enabled?(gates, actor)
+      actor_id = Actor.id(actor)
+      return false if actor_id.blank?
+
+      gates.any? { |gate| gate["key"] == "actors" && gate["value"] == actor_id }
+    end
+    private_class_method :actor_enabled?
+
+    def group_enabled?(gates, actor)
+      return false if actor.nil?
+
+      gates.any? { |gate| gate["key"] == "groups" && Group.member?(gate["value"], actor) }
+    end
+    private_class_method :group_enabled?
+
+    def percentage_enabled?(gates, name, actor)
+      return false if actor.nil?
+
+      gate = gates.find { |entry| entry["key"] == "percentage_of_actors" }
+      return false unless gate
+
+      Actor.percentage_value(actor, name) < gate["value"].to_i
+    end
+    private_class_method :percentage_enabled?
+  end
+end

data/lib/onni/sync.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Onni
+  # Configurable mutual exclusion for shared in-process state.
+  # On Ruby 3.4+, Mutex ownership is per Fiber, so :mutex covers threads and fibers.
+  # Do not Fiber.yield inside a synchronize block.
+  module Sync
+    BOOTSTRAP = Mutex.new
+
+    class NullLock
+      def synchronize
+        yield
+      end
+    end
+
+    module_function
+
+    def new_lock
+      case Onni.configuration.concurrency
+      when :mutex then Mutex.new
+      when :none then NullLock.new
+      else
+        raise ArgumentError, "Unknown Onni concurrency #{Onni.configuration.concurrency.inspect}"
+      end
+    end
+
+    def synchronize(&block)
+      shared_lock.synchronize(&block)
+    end
+
+    def reset!
+      BOOTSTRAP.synchronize { @shared_lock = nil }
+    end
+
+    def shared_lock
+      lock = @shared_lock
+      return lock if lock
+
+      BOOTSTRAP.synchronize { @shared_lock ||= new_lock }
+    end
+    private_class_method :shared_lock
+  end
+end

data/lib/onni/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Onni
+  VERSION = "0.1.0"
+end

data/lib/onni.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "zlib"
+require "json"
+require "onni/version"
+require "onni/configuration"
+require "onni/sync"
+require "onni/instrumenter"
+require "onni/registry"
+require "onni/actor"
+require "onni/group"
+require "onni/conditions"
+require "onni/stats"
+require "onni/flag"
+require "onni/request_store"
+require "onni/store"
+require "onni/adapters/memory"
+require "onni/adapters/active_record"
+require "onni/migrator/snapshot"
+require "onni/migrator/importer"
+require "onni/engine" if defined?(Rails::Engine)
+
+module Onni
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      Sync.reset!
+      @adapter = nil
+    end
+
+    def adapter
+      @adapter ||= build_adapter
+    end
+
+    attr_writer :adapter
+
+    def reset_adapter!
+      @adapter = nil
+    end
+
+    def enabled?(name, actor = nil, record_stats: true)
+      Store.enabled?(name, actor, record_stats: record_stats)
+    end
+
+    def disabled?(name, actor = nil, record_stats: true)
+      !enabled?(name, actor, record_stats: record_stats)
+    end
+
+    def variant(name, actor = nil, record_stats: true)
+      Store.variant(name, actor, record_stats: record_stats)
+    end
+
+    def enable(name, actor = nil)
+      feature_operation(name, :enable) do |payload|
+        add(name)
+        if actor
+          adapter.add_gate(name, "actors", Actor.id(actor))
+          payload[:actor_id] = Actor.id(actor)
+        else
+          adapter.add_gate(name, "boolean", "true")
+        end
+      end
+    end
+
+    def disable(name, actor = nil)
+      feature_operation(name, :disable) do |payload|
+        if actor
+          adapter.remove_gate(name, "actors", Actor.id(actor))
+          payload[:actor_id] = Actor.id(actor)
+        else
+          adapter.clear_gates(name)
+        end
+      end
+    end
+
+    def enable_group(name, group_name)
+      feature_operation(name, :enable_group, group_name: group_name.to_s) do
+        add(name)
+        adapter.add_gate(name, "groups", group_name.to_s)
+      end
+    end
+
+    def disable_group(name, group_name)
+      feature_operation(name, :disable_group, group_name: group_name.to_s) do
+        adapter.remove_gate(name, "groups", group_name.to_s)
+      end
+    end
+
+    def enable_percentage_of_actors(name, percentage)
+      clamped = percentage.to_i.clamp(0, 100)
+      feature_operation(name, :enable_percentage_of_actors, percentage: clamped) do
+        add(name)
+        adapter.remove_gate(name, "percentage_of_actors")
+        adapter.add_gate(name, "percentage_of_actors", clamped.to_s)
+      end
+    end
+
+    def set_variants(name, variants)
+      feature_operation(name, :set_variants) do
+        add(name)
+        adapter.remove_gate(name, "variants")
+        adapter.add_gate(name, "variants", JSON.generate(variants.transform_keys(&:to_s)))
+      end
+    end
+
+    def add(name)
+      Registry.require_definition!(name)
+      adapter.add(name)
+    end
+
+    def exist?(name)
+      adapter.exist?(name)
+    end
+
+    def features
+      adapter.feature_keys.map { |key| Flag.new(key) }
+    end
+
+    def [](name)
+      Flag.new(name)
+    end
+
+    def register_group(name, &block)
+      Group.register(name, &block)
+    end
+
+    # Import from any prior feature-flag store via a source with #feature_keys and #gates.
+    def migrate!(source)
+      Migrator::Importer.new(source).call
+    end
+
+    def sync_registry!
+      Registry.config.each_key { |key| add(key) unless exist?(key) }
+    end
+
+    def purge_stats!(**kwargs)
+      Stats.purge!(**kwargs)
+    end
+
+    def stats_overview
+      Stats.overview
+    end
+
+    # Preload gates into the fiber-local request store (one adapter round-trip).
+    # Pass names, or omit to load every YAML registry key.
+    def preload!(*names)
+      keys = names.flatten.map!(&:to_s)
+      keys = Registry.config.keys.map(&:to_s) if keys.empty?
+      loaded =
+        if adapter.respond_to?(:gates_for_many)
+          adapter.gates_for_many(keys)
+        else
+          keys.each_with_object({}) { |key, hash| hash[key] = adapter.gates_for(key) }
+        end
+      RequestStore.gates = (RequestStore.gates || {}).merge(loaded)
+      loaded.size
+    end
+
+    def flush_stats!
+      Stats::Buffer.flush!
+    end
+
+    def reset_request!
+      Stats::Buffer.flush! if configuration.stats_buffer
+      RequestStore.clear!
+    end
+
+    private
+
+    def feature_operation(name, operation, **fields)
+      Instrumenter.instrument("feature_operation", feature_name: name.to_s, operation: operation, **fields) do |payload|
+        Registry.require_definition!(name)
+        yield(payload)
+        Store.bust_cache!(name)
+        payload[:result] = true
+        true
+      end
+    end
+
+    def build_adapter
+      case configuration.adapter
+      when :memory then Adapters::Memory.new
+      when :active_record then Adapters::ActiveRecord.new
+      else
+        raise ArgumentError, "Unknown Onni adapter #{configuration.adapter.inspect}"
+      end
+    end
+  end
+end

data/onni.gemspec

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "lib/onni/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "onni"
+  spec.version = Onni::VERSION
+  spec.authors = ["Andrei Makarov"]
+  spec.email = ["contact@kiskolabs.com"]
+
+  spec.summary = "Feature flags, A/B variants, and hit stats for Ruby apps"
+  spec.description = <<~TEXT
+    Feature-flag and experiment core for any Ruby app: YAML registry, runtime hot
+    switches, actor and audience-group targeting, percentage / A/B assignment, and
+    hit stats for analysis. Not an authorization system. Optional ActiveRecord
+    adapter and pluggable ActiveAdmin dashboard. Includes a pluggable migrator
+    for importing gates from another feature-flag library.
+  TEXT
+  spec.license = "MIT"
+  spec.platform = Gem::Platform::RUBY
+  spec.required_ruby_version = ">= 3.4.0"
+
+  repository_url = "https://github.com/amkisko/onni.rb"
+
+  spec.homepage = repository_url
+  spec.metadata = {
+    "homepage_uri" => repository_url,
+    "source_code_uri" => "#{repository_url}/tree/main",
+    "changelog_uri" => "#{repository_url}/blob/main/CHANGELOG.md",
+    "bug_tracker_uri" => "#{repository_url}/issues",
+    "documentation_uri" => "#{repository_url}#readme",
+    "allowed_push_host" => "https://rubygems.org",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    %w[
+      CHANGELOG.md
+      CODE_OF_CONDUCT.md
+      CONTRIBUTING.md
+      GOVERNANCE.md
+      LICENSE.md
+      README.md
+      SECURITY.md
+      onni.gemspec
+    ].select { |path| File.file?(path) } +
+      Dir["{app,config,lib,sig}/**/*"]
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", ">= 7.2.3.2"
+
+  spec.add_development_dependency "activeadmin", ">= 4.0.0.beta23", "< 5"
+  spec.add_development_dependency "appraisal", "~> 2"
+  spec.add_development_dependency "bundler", ">= 2"
+  spec.add_development_dependency "bundler-audit", "~> 0.9"
+  spec.add_development_dependency "importmap-rails"
+  spec.add_development_dependency "polyrun", ">= 3.0.0"
+  spec.add_development_dependency "rails", ">= 7.2.3.2"
+  spec.add_development_dependency "rake", "~> 13"
+  spec.add_development_dependency "rbs", "~> 4"
+  spec.add_development_dependency "rspec", "~> 3"
+  spec.add_development_dependency "rspec-rails", ">= 6"
+  spec.add_development_dependency "sqlite3", ">= 2.10.2"
+  spec.add_development_dependency "rubocop-rspec", "~> 3.8"
+  spec.add_development_dependency "rubocop-thread_safety", "~> 0.7"
+  spec.add_development_dependency "standard", "~> 1.52"
+  spec.add_development_dependency "standard-custom", "~> 1.0"
+  spec.add_development_dependency "standard-performance", "~> 1.8"
+  spec.add_development_dependency "standard-rspec", "~> 0.3"
+end