magick-feature-flags 1.4.3 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e6f3b4ee81b2521e7f6975c0bd3c7a0a886ea2e23b5792b37e48cd28b08cb8d
-  data.tar.gz: 3aeb62560e637d844af0ea4e320a08a48eb72a33ebfd0653482899f42e8e2079
+  metadata.gz: 958764166d59a55b2243c5ce0f009164c26c75ae07740b200808866f3d6ad543
+  data.tar.gz: a96a1b187259c225a0b55ec243dbdfc9d9771621b420a4519c2fc7c4e9ee6a5c
 SHA512:
-  metadata.gz: 1135ba02b878e0d772259545231aa89f950e11199a0ee8d982440b9040f9c575a077567f3cd404727b27eb6eb962d811c6b301f92ad2227817289851392cf6c9
-  data.tar.gz: fb95eca4f8aa3b013298c087209818c91338ef4f9fe2a843951777df4c17fbe9bf83fdc5b1b45447503d5e718c6059d8a57b888746a36f463c929d8965526b3a
+  metadata.gz: 1affc66448028865d889535959d7970e8b54d1b3e3367d0bd4fb19ec8b18451c9bbc4714735e5f98f26da4a124e52b56a00c345d161660bfb944a9adb2bcbb12
+  data.tar.gz: 3ef2b6d8341517ef3bc8099a582e550877242d50f3fb67eab645b7d13f7adbdcf999f9f7a1d39e86ed3f5d1c13a98e8a69200dc5ab3b8c666cd14e924c462d0f

data/README.md

@@ -531,12 +531,58 @@ Magick.import(File.read('features.json'))
 
 #### Versioning and Rollback
 
+Every state-changing operation (value, status, group, targeting, exclusions,
+variants, dependencies, delete) automatically records a version snapshot and
+an audit entry — one per logical operation, under its real action name
+(`enable`, `exclude_user`, `set_status`, …). Nested internals never
+double-record.
+
 ```ruby
-# Save current state as version
+# History accumulates automatically:
+Magick[:my_feature].enable            # => version 1 (action: "enable")
+Magick[:my_feature].enable_for_user(42) # => version 2 (action: "enable_for_user")
+
+# Inspect history (hot window: last 50 versions by default)
+Magick.versioning.get_versions(:my_feature)
+
+# Include the unlimited ActiveRecord archive (when AR adapter is configured)
+Magick.versioning.get_versions(:my_feature, all: true)
+
+# Rollback fully restores a snapshot: value (including false/empty), status,
+# group, and the entire targeting hash — and records the rollback itself as a
+# new version, so history only ever rolls forward.
+Magick.versioning.rollback(:my_feature, 2)
+
+# Manual snapshots still work (action: "manual")
 Magick.versioning.save_version(:my_feature, created_by: current_user.id)
+```
+
+**Retention is tiered:** memory/Redis keep the last `max_versions` snapshots
+(default 50) for fast access; the ActiveRecord adapter keeps an unlimited
+archive that also survives feature deletion.
 
-# Rollback to previous version
-Magick.versioning.rollback(:my_feature, version: 2)
+```ruby
+Magick.configure do
+  versioning enabled: true, max_versions: 50
+end
+```
+
+**Attribution:** wrap changes in `Magick.with_actor` to stamp audit entries
+(`user_id`) and versions (`created_by`):
+
+```ruby
+Magick.with_actor(current_user.id) do
+  Magick[:my_feature].enable_for_user(42)
+end
+```
+
+**Boot replay is not recorded:** the Rails railtie loads `config/features.rb`
+inside `Magick.definition_mode`, so re-applying declarative definitions on
+every process boot does not flood history. Non-Rails apps should wrap their
+own definition file load the same way:
+
+```ruby
+Magick.definition_mode { load 'config/features.rb' }
 ```
 
 #### Performance Metrics
@@ -595,6 +641,11 @@ end
 
 #### Audit Logging
 
+Every mutation is logged under its real action name (`enable`, `disable`,
+`set_value`, `enable_for_user`, `exclude_role`, `set_status`, `set_group`,
+`delete`, `rollback`, …). One logical operation produces exactly one entry:
+`enable` no longer surfaces as a bare `set_value`.
+
 ```ruby
 # View audit log entries
 entries = Magick.audit_log.entries(feature_name: :my_feature, limit: 100)
@@ -603,6 +654,15 @@ entries.each do |entry|
 end
 ```
 
+In the Admin UI, configure a `current_actor` hook so every change made
+through the UI is attributed:
+
+```ruby
+Magick::AdminUI.configure do |config|
+  config.current_actor = ->(controller) { controller.session[:admin_id] }
+end
+```
+
 ## Architecture
 
 ### Adapters

data/app/controllers/magick/adminui/features_controller.rb

@@ -15,6 +15,9 @@ module Magick
       layout 'application'
       before_action :authenticate_admin!
       before_action :set_feature, only: %i[show edit update enable disable enable_for_user enable_for_role disable_for_role update_targeting update_variants]
+      # Attribute every change made during the request to the configured
+      # actor, so audit entries and version snapshots record who did it.
+      around_action :with_magick_actor
       # Render the TRUE current state, not this process's local cache. In a
       # multi-process / multi-container deployment the enable/disable POST and
       # the redirected GET are load-balanced to different processes, so the
@@ -321,6 +324,22 @@ module Magick
 
       private
 
+      # Resolve the acting admin via the configurable AdminUI hook and run the
+      # action inside Magick.with_actor. A failing resolver only costs
+      # attribution — it must never 500 the admin UI, and it is rescued
+      # separately so an action error is never swallowed or re-run.
+      def with_magick_actor(&block)
+        actor = begin
+          resolver = Magick::AdminUI.config.current_actor
+          resolver.respond_to?(:call) ? resolver.call(self) : nil
+        rescue StandardError => e
+          Rails.logger.warn "Magick: current_actor hook failed: #{e.class}: #{e.message}" if defined?(Rails)
+          nil
+        end
+
+        actor ? Magick.with_actor(actor, &block) : yield
+      end
+
       def authenticate_admin!
         return unless Magick::AdminUI.config.require_role
 

data/config/magick.rb.example

@@ -20,11 +20,13 @@ Magick.configure do
   # Enable performance metrics tracking
   performance_metrics enabled: true
 
-  # Enable audit logging
+  # Enable audit logging (every mutation is logged under its real action name)
   audit_log enabled: true
 
-  # Enable versioning support
-  versioning enabled: true
+  # Enable versioning (every save creates a version snapshot; allows rollback)
+  # max_versions caps the hot window kept in memory/Redis; the ActiveRecord
+  # adapter keeps an unlimited archive.
+  versioning enabled: true, max_versions: 50
 
   # Enable deprecation warnings
   warn_on_deprecated true

data/lib/generators/magick/install/templates/magick.rb

@@ -23,11 +23,13 @@ Magick.configure do
   # Enable performance metrics tracking
   performance_metrics enabled: true
 
-  # Enable audit logging (tracks who changed what, when)
+  # Enable audit logging (every mutation is logged under its real action name)
   audit_log enabled: true
 
-  # Enable versioning support (allows rollback)
-  versioning enabled: true
+  # Enable versioning (every save creates a version snapshot; allows rollback)
+  # max_versions caps the hot window kept in memory/Redis; the ActiveRecord
+  # adapter keeps an unlimited archive.
+  versioning enabled: true, max_versions: 50
 
   # Enable deprecation warnings in logs
   warn_on_deprecated enabled: true

data/lib/magick/adapters/registry.rb

@@ -176,7 +176,9 @@ module Magick
         features += memory_adapter.all_features if memory_adapter
         features += redis_adapter.all_features if redis_adapter
         features += active_record_adapter.all_features if active_record_adapter
-        features.uniq
+        # Version history is stored under a reserved pseudo-feature namespace;
+        # it is bookkeeping, not a feature.
+        features.uniq.reject { |f| f.to_s.start_with?(Versioning::STORE_PREFIX) }
       end
 
       # Load all keys for a single feature in one call instead of N separate get() calls
@@ -357,9 +359,13 @@ module Magick
         end
       end
 
+      # Public so Versioning can apply tiered retention: hot window written to
+      # memory/Redis, unlimited archive written to ActiveRecord only.
+      attr_reader :memory_adapter, :redis_adapter, :active_record_adapter
+
       private
 
-      attr_reader :memory_adapter, :redis_adapter, :active_record_adapter, :circuit_breaker
+      attr_reader :circuit_breaker
 
       # Signal the subscribe loop to return, then close the connection so any
       # retry/reconnect attempt fails fast instead of sleeping for 5s.

data/lib/magick/admin_ui.rb

@@ -17,7 +17,7 @@ module Magick
       end
 
       class Configuration
-        attr_accessor :theme, :brand_name, :require_role, :available_roles, :available_tags
+        attr_accessor :theme, :brand_name, :require_role, :available_roles, :available_tags, :current_actor
 
         def initialize
           @theme = :light
@@ -25,6 +25,10 @@ module Magick
           @require_role = nil
           @available_roles = [] # Can be populated via DSL: admin_ui { roles ['admin', 'user', 'manager'] }
           @available_tags = nil # Can be array or lambda: -> { Tag.all }
+          # Lambda receiving the controller, returning who is making the
+          # change; stamped onto audit entries (user_id) and versions
+          # (created_by): -> (controller) { controller.current_user&.id }
+          @current_actor = nil
         end
 
         # Get available tags, calling lambda if needed

data/lib/magick/config.rb

@@ -135,8 +135,11 @@ module Magick
                    end
     end
 
-    def versioning(enabled: true)
-      @versioning = (Versioning.new(adapter_registry || default_adapter_registry) if enabled)
+    def versioning(enabled: true, max_versions: Versioning::DEFAULT_MAX_VERSIONS)
+      @versioning_enabled = enabled
+      @versioning = if enabled
+                      Versioning.new(adapter_registry || default_adapter_registry, max_versions: max_versions)
+                    end
     end
 
     def circuit_breaker(threshold: nil, timeout: nil)
@@ -186,8 +189,11 @@ module Magick
         end
       end
 
-      Magick.audit_log = audit_log if audit_log
-      Magick.versioning = versioning if versioning
+      # Read the ivars directly: calling the DSL methods here would re-run
+      # them with their defaults and stomp explicit `enabled: false` settings.
+      Magick.audit_log = @audit_log if @audit_log
+      Magick.versioning = @versioning if @versioning
+      Magick.versioning_enabled = @versioning_enabled unless @versioning_enabled.nil?
       Magick.warn_on_deprecated = warn_on_deprecated
     end