magick-feature-flags 1.4.2 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce69954c64fae4d8ec9d10d177621ef508c1f0d8db98b9012849250d90cc974f
-  data.tar.gz: 41024341850d984dc1b16c8e85913160a94eb92b96f5eaf07477d9ff93a46de4
+  metadata.gz: 958764166d59a55b2243c5ce0f009164c26c75ae07740b200808866f3d6ad543
+  data.tar.gz: a96a1b187259c225a0b55ec243dbdfc9d9771621b420a4519c2fc7c4e9ee6a5c
 SHA512:
-  metadata.gz: a16aa4722424020d4d4ab0d45c1dc5bfec6452ae6f24177d713e6f98790d33b4851bb340e39603aecf52c06bf2d669d0876c0b3835bc9ebf4f63cd92e7776ccc
-  data.tar.gz: 3a49561daaf30a060abefd7c11413dd5e87e27771b59e089d287cb2788920f5f9c334c4922e064d03c18ce692b6f37a6bfeaf419f09ba12891313c3be1eb1f8a
+  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
@@ -904,10 +964,14 @@ Magick.shutdown!          # default 5 second join timeout
 Magick.shutdown!(timeout: 1)  # more aggressive
 ```
 
-Fork-based deployments (Puma workers with `preload_app`, Unicorn) are handled
-automatically: `config.to_prepare` calls `ensure_subscriber!` and
-`ensure_async_processor!` on every prepare cycle, so children that inherit
-stale parent threads start fresh. No action required from the host app.
+Fork-based deployments (Puma workers with `preload_app!`, Unicorn) are handled
+automatically. A Rack middleware (`Magick::Rails::SubscriberMiddleware`) calls
+`ensure_subscriber!` on each request — a pid-guarded no-op once the subscriber
+is running — so a worker that inherited a dead parent thread starts its own
+subscriber on its first request. This matters because in production
+`config.to_prepare` runs **once at boot** (before workers fork), not per
+request, so it cannot revive the subscriber inside forked workers on its own.
+No action required from the host app.
 
 ## Admin UI Security
 

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

@@ -15,6 +15,16 @@ 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
+      # process rendering the page may hold a stale memory copy until Pub/Sub
+      # catches up. These refresh from the shared backend before rendering.
+      before_action :refresh_all_features_from_source, only: %i[index]
+      before_action :refresh_feature_from_source, only: %i[show edit]
 
       # Make route helpers available in views via magick_admin_ui helper
       helper_method :magick_admin_ui, :available_roles, :available_tags, :partially_enabled?
@@ -314,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
 
@@ -334,6 +360,26 @@ module Magick
         obj.is_a?(Hash) || (defined?(ActionController::Parameters) && obj.is_a?(ActionController::Parameters))
       end
 
+      # Refresh every registered feature from the shared backend so the index
+      # reflects authoritative state regardless of which container serves it.
+      # Best-effort: a backend hiccup must never 500 the admin list.
+      def refresh_all_features_from_source
+        registry = Magick.adapter_registry
+        registry.refresh_all_from_source if registry.respond_to?(:refresh_all_from_source)
+        Magick.features.each_value { |f| f.reload if f.respond_to?(:reload) }
+      rescue StandardError => e
+        Rails.logger.warn "Magick: admin source refresh failed: #{e.class}: #{e.message}" if defined?(Rails)
+      end
+
+      # Refresh the single feature being viewed/edited from the shared backend.
+      def refresh_feature_from_source
+        return unless @feature
+
+        @feature.reload_from_source! if @feature.respond_to?(:reload_from_source!)
+      rescue StandardError => e
+        Rails.logger.warn "Magick: admin source refresh failed: #{e.class}: #{e.message}" if defined?(Rails)
+      end
+
       def set_feature
         feature_name = params[:id].to_s
         # Do NOT fall back to Magick[feature_name] — that would lazily create

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

@@ -24,7 +24,6 @@ module Magick
         @subscriber_thread = nil
         @subscriber = nil
         @refresh_thread = nil
-        @last_reload_times = {} # Track last reload time per feature for debouncing
         @local_writes = {} # Track recent local writes to skip self-invalidation
         @reload_mutex = Mutex.new
         @stopping = false
@@ -177,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
@@ -217,6 +218,39 @@ module Magick
         {}
       end
 
+      # Read a feature's complete data straight from the shared, authoritative
+      # backend — ActiveRecord first (it is written synchronously on every
+      # set/set_all_data), then Redis — bypassing this process's local memory
+      # cache, and refresh memory with the result.
+      #
+      # The Admin UI uses this so a toggle is reflected immediately on whichever
+      # process/container serves the (load-balanced) request after the write,
+      # instead of rendering this process's possibly-stale memory cache while it
+      # waits for Pub/Sub invalidation to arrive.
+      def authoritative_get_all_data(feature_name)
+        data = read_from_source(feature_name)
+        if data && !data.empty?
+          memory_adapter&.set_all_data(feature_name, data)
+          return data
+        end
+
+        # Source unavailable (Redis/AR down, or feature absent there) — fall back
+        # to whatever this process already has rather than wiping a usable cache.
+        memory_adapter ? memory_adapter.get_all_data(feature_name) : {}
+      end
+
+      # Bulk variant of #authoritative_get_all_data: refresh the local memory
+      # cache for EVERY feature from the shared backend in 1-2 queries. Returns
+      # the loaded data. Used by the Admin UI index so the full list reflects
+      # authoritative state regardless of which container serves it.
+      def refresh_all_from_source
+        data = load_all_from_source
+        if memory_adapter && !data.empty?
+          data.each { |feature_name, feature_data| memory_adapter.set_all_data(feature_name, feature_data) }
+        end
+        data
+      end
+
       # Bulk load ALL features into memory cache in minimal queries.
       # Call this after configuration to warm the cache.
       def preload!
@@ -325,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.
@@ -371,6 +409,101 @@ module Magick
         thread
       end
 
+      # Handle one cache-invalidation message: refresh this process's view of
+      # the feature from the shared backend. Returns true when the message was
+      # acted on, false when it was rejected/skipped (used by specs).
+      #
+      # Every VALID, non-self message triggers a full-state reload. We do NOT
+      # debounce by a time window: a single enable/disable emits two publishes
+      # (targeting then value), and dropping the second would leave this process
+      # holding the old value until its memory TTL expires. Each reload reads the
+      # feature's COMPLETE current state, so processing every message is
+      # idempotent, and feature-flag writes are admin-rate — redundant reloads
+      # are cheap and rare.
+      def process_cache_invalidation(feature_name)
+        feature_name_str = feature_name.to_s
+
+        # Reject malformed payloads before doing anything with them. A shared
+        # Redis DB is not a trust boundary — reject anything that isn't a
+        # plausible feature identifier.
+        unless FEATURE_NAME_PATTERN.match?(feature_name_str)
+          warn "Magick: ignoring malformed pubsub payload (#{feature_name_str.bytesize}B)" if rails_development?
+          return false
+        end
+
+        # Skip self-invalidation: if this process just wrote this feature, memory
+        # already has the correct value. Reloading would revert it to stale data
+        # (especially with async writes that publish after the Redis write).
+        if local_write?(feature_name_str)
+          Rails.logger.debug "Magick: Skipping self-invalidation for '#{feature_name_str}'" if rails_development?
+          return false
+        end
+
+        # Invalidate the local memory cache, then reload the registered feature
+        # instance from the shared backend (the publisher writes Redis/AR BEFORE
+        # publishing, so fresh data is available by now).
+        memory_adapter&.delete(feature_name_str)
+        if defined?(Magick) && Magick.respond_to?(:features) && Magick.features.key?(feature_name_str)
+          feature = Magick.features[feature_name_str]
+          if feature.respond_to?(:reload)
+            feature.reload
+            Rails.logger.debug "Magick: Reloaded '#{feature_name_str}' after cache invalidation" if rails_development?
+          end
+        end
+        true
+      end
+
+      def rails_development?
+        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.development?
+      end
+
+      # Read a feature's full data from the shared, authoritative backend,
+      # skipping the local memory cache. ActiveRecord is preferred because it is
+      # written synchronously on every set (Redis may lag under async_updates).
+      def read_from_source(feature_name)
+        if active_record_adapter
+          begin
+            data = active_record_adapter.get_all_data(feature_name)
+            return data if data && !data.empty?
+          rescue StandardError, AdapterError
+            # fall through to Redis
+          end
+        end
+
+        if redis_adapter
+          begin
+            return circuit_breaker.call { redis_adapter.get_all_data(feature_name) }
+          rescue StandardError, AdapterError
+            nil
+          end
+        end
+
+        nil
+      end
+
+      # Bulk read ALL features from the shared, authoritative backend, skipping
+      # the local memory cache. AR preferred (synchronous), Redis fallback.
+      def load_all_from_source
+        if active_record_adapter
+          begin
+            data = active_record_adapter.load_all_features_data
+            return data if data && !data.empty?
+          rescue StandardError, AdapterError
+            # fall through to Redis
+          end
+        end
+
+        if redis_adapter
+          begin
+            return circuit_breaker.call { redis_adapter.load_all_features_data } || {}
+          rescue StandardError, AdapterError
+            {}
+          end
+        end
+
+        {}
+      end
+
       # Record that this process just wrote a feature, so the subscriber
       # ignores its own Pub/Sub messages and doesn't revert the correct in-memory state.
       def record_local_write(feature_name)
@@ -378,7 +511,7 @@ module Magick
           @local_writes[feature_name.to_s] = Time.now.to_f
           # Also sweep stale tracking entries on the write path — a write-heavy
           # process that rarely reads would otherwise never trigger cleanup,
-          # letting @local_writes and @last_reload_times grow unboundedly.
+          # letting @local_writes grow unboundedly.
           cleanup_stale_tracking_entries
         end
       end
@@ -408,7 +541,6 @@ module Magick
 
         @last_tracking_cleanup = now
         @local_writes.delete_if { |_, wrote_at| (now - wrote_at) >= LOCAL_WRITE_TTL }
-        @last_reload_times.delete_if { |_, reload_at| (now - reload_at) >= 10.0 }
       end
 
       # Start a background thread to listen for cache invalidation messages
@@ -442,56 +574,7 @@ module Magick
 
           @subscriber.subscribe(CACHE_INVALIDATION_CHANNEL) do |on|
             on.message do |_channel, feature_name|
-              feature_name_str = feature_name.to_s
-
-              # Reject malformed payloads before doing anything with them.
-              # A shared Redis DB is not a trust boundary — reject anything
-              # that isn't a plausible feature identifier.
-              unless FEATURE_NAME_PATTERN.match?(feature_name_str)
-                if defined?(Rails) && Rails.env.development?
-                  warn "Magick: ignoring malformed pubsub payload (#{feature_name_str.bytesize}B)"
-                end
-                next
-              end
-
-              # Skip self-invalidation: if this process just wrote this feature,
-              # memory already has the correct value. Reloading from Redis would
-              # revert it to stale data (especially with async writes).
-              if local_write?(feature_name_str)
-                if defined?(Rails) && Rails.env.development?
-                  Rails.logger.debug "Magick: Skipping self-invalidation for '#{feature_name_str}'"
-                end
-                next
-              end
-
-              # Debounce: only reload if we haven't reloaded this feature in the last 100ms
-              should_reload = @reload_mutex.synchronize do
-                last_reload = @last_reload_times[feature_name_str]
-                now = Time.now.to_f
-                if last_reload.nil? || (now - last_reload) > 0.1 # 100ms debounce
-                  @last_reload_times[feature_name_str] = now
-                  true
-                else
-                  false
-                end
-              end
-
-              next unless should_reload
-
-              # Invalidate memory cache for this feature
-              memory_adapter.delete(feature_name_str) if memory_adapter
-
-              # Reload the feature instance from the adapter (Redis should have fresh data
-              # since remote processes publish AFTER their Redis write completes)
-              if defined?(Magick) && Magick.features.key?(feature_name_str)
-                feature = Magick.features[feature_name_str]
-                if feature.respond_to?(:reload)
-                  feature.reload
-                  if defined?(Rails) && Rails.env.development?
-                    Rails.logger.debug "Magick: Reloaded feature '#{feature_name_str}' after cache invalidation"
-                  end
-                end
-              end
+              process_cache_invalidation(feature_name)
             rescue StandardError => e
               # Log error but don't crash the subscriber thread
               # Skip logging RSpec mock errors in test environments

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