magick-feature-flags 1.4.3 → 1.6.0

data/lib/magick/rails/railtie.rb

@@ -87,15 +87,18 @@ if defined?(Rails)
           # Supports both config/features.rb and config/initializers/features.rb
           config.after_initialize do
             # Try config/features.rb first (recommended location)
+            # definition_mode suppresses audit/version recording: boot replays
+            # the declarative definitions in every container, and recording
+            # those would flood history with identical snapshots.
             features_file = Rails.root.join('config', 'features.rb')
             if File.exist?(features_file)
-              load features_file
+              Magick.definition_mode { load features_file }
             else
               # Fallback to config/initializers/features.rb (already loaded by Rails, but check anyway)
               initializer_file = Rails.root.join('config', 'initializers', 'features.rb')
               if File.exist?(initializer_file) && !defined?(Magick::Rails::FeaturesLoaded)
                 # Only load if not already loaded (Rails may have already loaded it)
-                load initializer_file
+                Magick.definition_mode { load initializer_file }
               end
             end
             begin

data/lib/magick/targeting_payload.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'time'
+
+module Magick
+  # Translates between the internal targeting hash and the wire-format
+  # targeting payload exchanged with control planes (panel contract):
+  #
+  #   GET  -> Feature#as_json emits `serialize(targeting)` — string keys,
+  #           arrays of strings, floats; the "targeting" key is always
+  #           present ({} = no targeting).
+  #   PATCH -> Feature#replace_targeting runs the inbound payload through
+  #           `normalize` — lenient about aliases/scalars/key types, strict
+  #           about vocabulary and values (all-or-nothing).
+  #
+  # The internal-only :variants key never crosses the wire in either
+  # direction: `serialize` drops it, `normalize` rejects it.
+  module TargetingPayload
+    # Inclusion keys are singular, exclusion keys plural — mirrors the
+    # internal @targeting layout, which is also the persisted layout.
+    ARRAY_KEYS = %i[
+      user group role tag ip_address
+      excluded_users excluded_groups excluded_roles excluded_tags excluded_ip_addresses
+    ].freeze
+    PERCENTAGE_KEYS = %i[percentage_users percentage_requests].freeze
+    STRUCTURED_KEYS = %i[date_range custom_attributes complex_conditions].freeze
+    CANONICAL_KEYS = (ARRAY_KEYS + PERCENTAGE_KEYS + STRUCTURED_KEYS).freeze
+
+    # Plural spellings accepted on input for parity with Magick.import.
+    ALIASES = {
+      users: :user,
+      groups: :group,
+      roles: :role,
+      tags: :tag,
+      ip_addresses: :ip_address
+    }.freeze
+
+    IP_KEYS = %i[ip_address excluded_ip_addresses].freeze
+
+    CUSTOM_ATTRIBUTE_OPERATORS = %i[equals eq not_equals ne in not_in greater_than gt less_than lt].freeze
+    COMPLEX_OPERATORS = %i[and or].freeze
+    COMPLEX_CONDITION_TYPES = %i[user group role custom_attribute].freeze
+
+    module_function
+
+    # Wire payload -> canonical internal targeting hash. Raises
+    # InvalidTargetingError on the first problem, before any state is
+    # touched, so callers get all-or-nothing semantics for free.
+    def normalize(payload)
+      raise InvalidTargetingError, "targeting must be a Hash, got #{payload.class}" unless payload.is_a?(Hash)
+
+      normalized = {}
+      payload.each do |raw_key, raw_value|
+        key = canonical_key(raw_key)
+        raise InvalidTargetingError, "conflicting targeting keys resolve to '#{key}'" if normalized.key?(key)
+        next if raw_value.nil? # nil = remove the rule, same as omitting the key
+
+        value = normalize_value(key, raw_value)
+        normalized[key] = value unless value.nil?
+      end
+      normalized
+    end
+
+    # Internal targeting hash -> wire payload. Never raises: the read path
+    # must serialize whatever historical state an adapter hands back.
+    def serialize(targeting)
+      return {} unless targeting.is_a?(Hash)
+
+      targeting.each_with_object({}) do |(key, value), wire|
+        key = key.to_sym
+        next if key == :variants # internal-only, managed via set_variants
+
+        wire[key.to_s] =
+          if ARRAY_KEYS.include?(key)
+            Array(value).map(&:to_s)
+          elsif PERCENTAGE_KEYS.include?(key)
+            value.to_f
+          elsif key == :date_range
+            serialize_date_range(value)
+          else
+            deep_stringify(value)
+          end
+      end
+    end
+
+    def canonical_key(raw_key)
+      key = raw_key.to_sym
+      key = ALIASES.fetch(key, key)
+      if key == :variants
+        raise InvalidTargetingError, 'variants are not part of the targeting payload (use set_variants)'
+      end
+      raise InvalidTargetingError, "unknown targeting key: '#{raw_key}'" unless CANONICAL_KEYS.include?(key)
+
+      key
+    end
+
+    def normalize_value(key, value)
+      if ARRAY_KEYS.include?(key)
+        normalize_array(key, value)
+      elsif PERCENTAGE_KEYS.include?(key)
+        normalize_percentage(key, value)
+      elsif key == :date_range
+        normalize_date_range(value)
+      elsif key == :custom_attributes
+        normalize_custom_attributes(value)
+      else # :complex_conditions
+        normalize_complex_conditions(value)
+      end
+    end
+
+    # Scalars are accepted as one-element lists; empty lists mean "no rule"
+    # and collapse to key removal, keeping {} the only spelling of
+    # "no targeting".
+    def normalize_array(key, value)
+      values = (value.is_a?(Array) ? value : [value]).compact.map { |v| v.to_s.strip }.reject(&:empty?).uniq
+      return nil if values.empty?
+
+      validate_ip_list!(key, values) if IP_KEYS.include?(key)
+      values
+    end
+
+    def validate_ip_list!(key, values)
+      values.each do |ip|
+        IPAddr.new(ip)
+      rescue ArgumentError # includes IPAddr::Error
+        raise InvalidTargetingError, "invalid IP address or CIDR range in '#{key}': '#{ip}'"
+      end
+    end
+
+    def normalize_percentage(key, value)
+      percentage = begin
+        Float(value)
+      rescue ArgumentError, TypeError
+        raise InvalidTargetingError, "'#{key}' must be a number, got #{value.inspect}"
+      end
+      unless percentage.positive? && percentage <= 100
+        raise InvalidTargetingError, "'#{key}' must be within (0, 100], got #{percentage}"
+      end
+
+      percentage
+    end
+
+    def normalize_date_range(value)
+      raise InvalidTargetingError, "'date_range' must be a Hash with start and end" unless value.is_a?(Hash)
+
+      start_value = value[:start] || value['start']
+      end_value = value[:end] || value['end']
+      raise InvalidTargetingError, "'date_range' requires both start and end" unless start_value && end_value
+
+      { start: parse_date_bound(start_value), end: parse_date_bound(end_value) }
+    end
+
+    def parse_date_bound(value)
+      return value unless value.is_a?(String)
+
+      Time.parse(value)
+      value
+    rescue ArgumentError
+      raise InvalidTargetingError, "'date_range' bound is not a parseable time: '#{value}'"
+    end
+
+    def normalize_custom_attributes(value)
+      raise InvalidTargetingError, "'custom_attributes' must be a Hash" unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(attribute, rule), result|
+        raise InvalidTargetingError, "rule for custom attribute '#{attribute}' must be a Hash" unless rule.is_a?(Hash)
+
+        values = Array(rule[:values] || rule['values']).compact.map(&:to_s).reject(&:empty?)
+        raise InvalidTargetingError, "custom attribute '#{attribute}' requires values" if values.empty?
+
+        operator = (rule[:operator] || rule['operator'] || :equals).to_sym
+        unless CUSTOM_ATTRIBUTE_OPERATORS.include?(operator)
+          raise InvalidTargetingError, "unknown operator '#{operator}' for custom attribute '#{attribute}'"
+        end
+
+        result[attribute.to_sym] = { values: values, operator: operator }
+      end
+    end
+
+    def normalize_complex_conditions(value)
+      raise InvalidTargetingError, "'complex_conditions' must be a Hash" unless value.is_a?(Hash)
+
+      operator = (value[:operator] || value['operator'] || :and).to_sym
+      unless COMPLEX_OPERATORS.include?(operator)
+        raise InvalidTargetingError, "'complex_conditions' operator must be and/or, got '#{operator}'"
+      end
+
+      conditions = value[:conditions] || value['conditions']
+      raise InvalidTargetingError, "'complex_conditions' requires a conditions Array" unless conditions.is_a?(Array)
+
+      { operator: operator, conditions: conditions.map { |c| normalize_complex_condition(c) } }
+    end
+
+    def normalize_complex_condition(condition)
+      raise InvalidTargetingError, 'each complex condition must be a Hash' unless condition.is_a?(Hash)
+
+      type = (condition[:type] || condition['type']).to_s.to_sym
+      unless COMPLEX_CONDITION_TYPES.include?(type)
+        raise InvalidTargetingError, "unknown complex condition type: '#{type}'"
+      end
+
+      params = condition[:params] || condition['params'] || {}
+      raise InvalidTargetingError, "params for complex condition '#{type}' must be a Hash" unless params.is_a?(Hash)
+
+      { type: type, params: params.transform_keys(&:to_sym) }
+    end
+
+    def serialize_date_range(value)
+      return deep_stringify(value) unless value.is_a?(Hash)
+
+      start_value = value[:start] || value['start']
+      end_value = value[:end] || value['end']
+      { 'start' => serialize_time(start_value), 'end' => serialize_time(end_value) }
+    end
+
+    def serialize_time(value)
+      return value if value.nil? || value.is_a?(String)
+      return value.iso8601 if value.respond_to?(:iso8601)
+
+      value.to_s
+    end
+
+    def deep_stringify(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify(v) }
+      when Array
+        value.map { |v| deep_stringify(v) }
+      when Symbol
+        value.to_s
+      else
+        value
+      end
+    end
+  end
+end

data/lib/magick/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Magick
-  VERSION = '1.4.3'
+  VERSION = '1.6.0'
 end

data/lib/magick/versioning.rb

@@ -1,15 +1,26 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'time'
+
 module Magick
   class Versioning
+    DEFAULT_MAX_VERSIONS = 50
+
+    # Version history lives under a reserved pseudo-feature namespace so that
+    # feature reads (get_all_data) never drag snapshot blobs along, and so
+    # deleting a feature does not destroy its ActiveRecord archive row.
+    STORE_PREFIX = '__magick_versions:'
+
     class Version
-      attr_reader :version, :feature_data, :timestamp, :created_by
+      attr_reader :version, :feature_data, :timestamp, :created_by, :action
 
-      def initialize(version, feature_data, created_by: nil)
+      def initialize(version, feature_data, created_by: nil, action: nil, timestamp: nil)
         @version = version
         @feature_data = feature_data
-        @timestamp = Time.now
+        @timestamp = timestamp || Time.now
         @created_by = created_by
+        @action = action
       end
 
       def to_h
@@ -17,66 +28,65 @@ module Magick
           version: version,
           feature_data: feature_data,
           timestamp: timestamp.iso8601,
-          created_by: created_by
+          created_by: created_by,
+          action: action
         }
       end
     end
 
-    def initialize(adapter_registry)
+    def initialize(adapter_registry, max_versions: DEFAULT_MAX_VERSIONS)
       @adapter_registry = adapter_registry
-      @versions = {}
+      @max_versions = max_versions.to_i.positive? ? max_versions.to_i : DEFAULT_MAX_VERSIONS
+      # Process-local cache of the hot window, rehydrated lazily from the
+      # adapters so history survives restarts and is shared across containers.
+      @hot = {}
       @mutex = Mutex.new
     end
 
+    attr_reader :max_versions
+
+    # Explicit manual snapshot. Kept as public API from earlier releases;
+    # since 1.5.0 every Feature mutation also snapshots automatically.
     def save_version(feature_name, version: nil, created_by: nil)
       feature = Magick.features[feature_name.to_s] || Magick[feature_name]
-      feature_name_str = feature_name.to_s
-
-      # Compute version + append under the same mutex so two concurrent
-      # save_version calls on the same feature can't both assign version N.
-      version_data = @mutex.synchronize do
-        list = (@versions[feature_name_str] ||= [])
-        resolved_version = version || (list.empty? ? 1 : list.last.version + 1)
-        entry = Version.new(resolved_version, feature.to_h, created_by: created_by)
-        list << entry
-        @adapter_registry.set(feature_name, "version_#{resolved_version}", entry.to_h)
-        entry
-      end
+      append(feature.name, snapshot_of(feature), version: version, created_by: created_by, action: 'manual')
+    end
 
-      if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
-        Magick::Rails::Events.version_saved(feature_name, version: version_data.version, created_by: created_by)
-      end
+    # Called by Feature#record_change after every successful mutation.
+    # snapshot: allows callers (delete) to capture state before the mutation.
+    def record_change(feature, action: nil, created_by: nil, snapshot: nil)
+      data = snapshot ? deep_symbolize(JSON.parse(JSON.generate(snapshot))) : snapshot_of(feature)
+      append(feature.name, data, created_by: created_by, action: action)
+    end
+
+    # Hot window (last max_versions, memory/Redis) by default; all: true
+    # merges the unlimited ActiveRecord archive when one is configured.
+    def get_versions(feature_name, all: false)
+      name = feature_name.to_s
+      hot = @mutex.synchronize { hot_window(name).dup }
+      return hot unless all
 
-      version_data
+      older = archive_versions(name).reject { |a| hot.any? { |h| h.version == a.version } }
+      (older + hot).sort_by(&:version)
     end
 
+    # Restore the feature to the snapshot stored in the given version, then
+    # record the rollback itself as a new version + audit entry (history only
+    # ever rolls forward). Restores state wholesale: value (including false/
+    # empty), status, group, the entire targeting hash, and dependencies.
     def rollback(feature_name, version)
-      versions = get_versions(feature_name)
-      target_version = versions.find { |v| v.version == version }
-      return false unless target_version
+      entry = find_version(feature_name, version)
+      return false unless entry
 
       feature = Magick.features[feature_name.to_s] || Magick[feature_name]
-      feature_data = target_version.feature_data
-
-      # Restore feature state
-      feature.set_value(feature_data[:value]) if feature_data[:value]
-      feature.set_status(feature_data[:status]) if feature_data[:status]
-
-      # Restore targeting
-      feature_data[:targeting]&.each do |type, values|
-        Array(values).each do |value|
-          case type.to_sym
-          when :user
-            feature.enable_for_user(value)
-          when :group
-            feature.enable_for_group(value)
-          when :role
-            feature.enable_for_role(value)
-          end
-        end
+      Magick.suppress_change_recording do
+        feature.restore_snapshot!(entry.feature_data)
       end
 
-      # Rails 8+ event
+      actor = Magick.current_actor
+      Magick.audit_log&.log(feature_name, 'rollback', user_id: actor, changes: { rolled_back_to: version })
+      record_change(feature, action: 'rollback', created_by: actor)
+
       if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
         Magick::Rails::Events.rollback(feature_name, version: version)
       end
@@ -84,17 +94,161 @@ module Magick
       true
     end
 
-    def get_versions(feature_name)
-      @mutex.synchronize { (@versions[feature_name.to_s] || []).dup }
+    private
+
+    # Deep copy via JSON so stored snapshots never alias the feature's live
+    # targeting hash, and in-process entries match adapter-rehydrated ones.
+    def snapshot_of(feature)
+      deep_symbolize(JSON.parse(JSON.generate(feature.to_h)))
     end
 
-    private
+    def append(name, snapshot, version: nil, created_by: nil, action: nil)
+      entry = @mutex.synchronize do
+        window = hot_window(name)
+        resolved = version || (window.last ? window.last.version + 1 : 1)
+        record = Version.new(resolved, snapshot, created_by: created_by, action: action)
+        window << record
+        window.shift while window.size > @max_versions
+        persist_hot_window(name, window)
+        persist_archive(name, record)
+        record
+      end
+
+      if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
+        Magick::Rails::Events.version_saved(name, version: entry.version, created_by: created_by)
+      end
+
+      entry
+    end
+
+    # Callers must hold @mutex.
+    def hot_window(name)
+      @hot[name] ||= load_hot_window(name)
+    end
+
+    def load_hot_window(name)
+      raw = read_hot_list(name)
+      raw = read_archive_tail(name) if raw.nil? || raw.empty?
+      Array(raw).filter_map { |h| rehydrate(h) }.sort_by(&:version).last(@max_versions)
+    end
+
+    def read_hot_list(name)
+      hot_adapters.each do |adapter|
+        list = safely { adapter.get(store_name(name), 'versions') }
+        list = parse_json(list) if list.is_a?(String)
+        return list if list.is_a?(Array) && !list.empty?
+      end
+      nil
+    end
+
+    # Seed the hot window from the archive when memory/Redis are empty
+    # (fresh boot, Redis flush) so version numbering continues, not restarts.
+    def read_archive_tail(name)
+      adapter = archive_adapter
+      return nil unless adapter
+
+      data = safely { adapter.get_all_data(store_name(name)) }
+      return nil unless data.is_a?(Hash)
 
-    def next_version(feature_name)
-      @mutex.synchronize do
-        list = @versions[feature_name.to_s] || []
-        list.empty? ? 1 : list.last.version + 1
+      data.filter_map { |key, value| value if key.to_s.start_with?('version_') }
+    end
+
+    def archive_versions(name)
+      adapter = archive_adapter
+      return [] unless adapter
+
+      data = safely { adapter.get_all_data(store_name(name)) }
+      return [] unless data.is_a?(Hash)
+
+      data.filter_map { |key, value| rehydrate(value) if key.to_s.start_with?('version_') }.sort_by(&:version)
+    end
+
+    def persist_hot_window(name, window)
+      payload = window.map(&:to_h)
+      hot_adapters.each do |adapter|
+        safely { adapter.set(store_name(name), 'versions', payload) }
       end
     end
+
+    def persist_archive(name, entry)
+      adapter = archive_adapter
+      return unless adapter
+
+      safely { adapter.set(store_name(name), "version_#{entry.version}", entry.to_h) }
+    end
+
+    def find_version(feature_name, version)
+      name = feature_name.to_s
+      hot = @mutex.synchronize { hot_window(name).dup }
+      found = hot.find { |v| v.version == version }
+      return found if found
+
+      adapter = archive_adapter
+      return nil unless adapter
+
+      raw = safely { adapter.get(store_name(name), "version_#{version}") }
+      raw ? rehydrate(raw) : nil
+    end
+
+    # Hot window lives in memory + Redis (capped); the ActiveRecord adapter
+    # keeps the unlimited archive, one version_<n> key per entry.
+    def hot_adapters
+      registry = @adapter_registry
+      if registry.respond_to?(:memory_adapter)
+        [registry.memory_adapter, registry.redis_adapter].compact
+      else
+        [registry]
+      end
+    end
+
+    def archive_adapter
+      registry = @adapter_registry
+      registry.respond_to?(:active_record_adapter) ? registry.active_record_adapter : nil
+    end
+
+    def store_name(name)
+      "#{STORE_PREFIX}#{name}"
+    end
+
+    def rehydrate(raw)
+      raw = parse_json(raw) if raw.is_a?(String)
+      return nil unless raw.is_a?(Hash)
+
+      data = deep_symbolize(raw)
+      timestamp = data[:timestamp]
+      timestamp = safely { Time.parse(timestamp) } if timestamp.is_a?(String)
+      Version.new(
+        data[:version],
+        data[:feature_data] || {},
+        created_by: data[:created_by],
+        action: data[:action],
+        timestamp: timestamp
+      )
+    end
+
+    def parse_json(str)
+      JSON.parse(str)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def deep_symbolize(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) { |(k, v), out| out[k.to_sym] = deep_symbolize(v) }
+      when Array
+        obj.map { |v| deep_symbolize(v) }
+      else
+        obj
+      end
+    end
+
+    # Version bookkeeping is best-effort: a flaky adapter must never turn a
+    # feature toggle into an exception.
+    def safely
+      yield
+    rescue StandardError
+      nil
+    end
   end
 end

data/lib/magick.rb

@@ -23,6 +23,7 @@ require_relative 'magick/targeting/ip_address'
 require_relative 'magick/targeting/custom_attribute'
 require_relative 'magick/targeting/complex'
 require_relative 'magick/errors'
+require_relative 'magick/targeting_payload'
 
 require_relative 'magick/log_safe'
 require_relative 'magick/audit_log'
@@ -216,6 +217,64 @@ module Magick
       @versioning ||= Versioning.new(adapter_registry || default_adapter_registry)
     end
 
+    # When false, Feature#record_change skips version snapshots (audit log
+    # entries are still written). Set via `versioning enabled: false` in the
+    # configuration DSL.
+    attr_writer :versioning_enabled
+
+    def versioning_enabled?
+      @versioning_enabled.nil? || @versioning_enabled != false
+    end
+
+    # Attribute all changes made inside the block to the given actor. Audit
+    # entries pick it up as user_id and versions as created_by, unless the
+    # call site passes an explicit user_id:.
+    #
+    #   Magick.with_actor(current_user.id) { Magick[:checkout].enable }
+    def with_actor(actor)
+      previous = Thread.current[:magick_actor]
+      Thread.current[:magick_actor] = actor
+      yield
+    ensure
+      Thread.current[:magick_actor] = previous
+    end
+
+    def current_actor
+      Thread.current[:magick_actor]
+    end
+
+    # Suppress audit/version recording while declarative feature definitions
+    # are (re)applied. Process boot replays config/features.rb in every
+    # container; recording those replays would flood history with identical
+    # snapshots. The Rails railtie wraps the features file load in this;
+    # non-Rails apps should do the same around their definition file.
+    def definition_mode
+      previous = Thread.current[:magick_definition_mode]
+      Thread.current[:magick_definition_mode] = true
+      yield
+    ensure
+      Thread.current[:magick_definition_mode] = previous
+    end
+
+    def definition_mode?
+      Thread.current[:magick_definition_mode] == true
+    end
+
+    # Reentrancy guard for Feature#record_change: the outermost public
+    # mutator records once; nested mutator calls (enable -> set_value) run
+    # silently so one logical operation never produces multiple entries.
+    def suppress_change_recording
+      previous = Thread.current[:magick_change_recording]
+      Thread.current[:magick_change_recording] = true
+      yield
+    ensure
+      Thread.current[:magick_change_recording] = previous
+    end
+
+    def change_recording_suppressed?
+      Thread.current[:magick_change_recording] == true || definition_mode?
+    end
+
     # Manually enable Redis tracking for performance metrics
     # Useful if Redis adapter becomes available after initial configuration
     def enable_redis_tracking(enable: true)
@@ -280,6 +339,9 @@ module Magick
       @adapter_registry = nil
       @default_adapter = nil
       @default_adapter_registry = nil
+      @versioning = nil
+      @audit_log = nil
+      @versioning_enabled = nil
       @performance_metrics&.clear!
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: magick-feature-flags
 version: !ruby/object:Gem::Version
-  version: 1.4.3
+  version: 1.6.0
 platform: ruby
 authors:
 - Andrew Lobanov
@@ -145,6 +145,7 @@ files:
 - lib/magick/targeting/request_percentage.rb
 - lib/magick/targeting/role.rb
 - lib/magick/targeting/user.rb
+- lib/magick/targeting_payload.rb
 - lib/magick/testing_helpers.rb
 - lib/magick/version.rb
 - lib/magick/versioning.rb