magick-feature-flags 1.4.3 → 1.5.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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Magick
-  VERSION = '1.4.3'
+  VERSION = '1.5.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

@@ -216,6 +216,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 +338,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.5.0
 platform: ruby
 authors:
 - Andrew Lobanov