magick-feature-flags 1.3.1 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a34f03026e8631bc2d29c0935cb98e472e7ed387fc4628edc357776423bfc2c5
-  data.tar.gz: d87af21843efb22d5dba60d342f3beb5fd807eb42f1b2948c82ae8dc3d6b67a2
+  metadata.gz: 3df9cccb3e3478e71402fa478d4a70401d0150290fdca89a6a47df7fbd901794
+  data.tar.gz: 929990ca6220cebb2e9215a1993df11fa25a71dbf620029a176db1c8b50edf48
 SHA512:
-  metadata.gz: '0296397245455dbecd448a2dab448b2209579f4c9c39a1e93b424e8f6982fe8a3f498140ac7af5f1127c70fc2cdaa3378194135afe2e55fe9254646a4c761e64'
-  data.tar.gz: 43e1ce6dcf51815f83ccf4440845d415f8d351e6a6038c8f7bcd0a294dfc0def6531a04a118119d66e71a64d7cfcc1607273eda0c181dfdf951c9ee61d4cfae7
+  metadata.gz: 225fdbbed5820df1ca9cb7f0283172b57ab5a3c0a26639fc6d11cef9553f80cc35402753878469db7470ef90ac691431daf399cac1b1cba26d23395ce5776f8c
+  data.tar.gz: da03312e98129cc04bc0ba63dfc06e67e171406e35fa4e46f9ff73c494a0596ef4e1e65868bab0a0ad7f43f05bbf449a81d9ac1b25eae5a0d40e1ba6245f4e44

data/README.md

@@ -888,6 +888,43 @@ end
 - `:inactive` - Feature is disabled for everyone
 - `:deprecated` - Feature is deprecated (can be enabled with `allow_deprecated: true` in context)
 
+## Graceful Shutdown
+
+Magick starts a background Redis Pub/Sub subscriber thread for cross-process
+cache invalidation and an asynchronous metrics processor. Both must be
+stopped before the host process exits or Puma's graceful-stop will block on
+the still-running `Redis#subscribe` call.
+
+The Railtie registers an `at_exit` hook that calls `Magick.shutdown!`
+automatically, so most Rails apps don't need to do anything. In long-running
+non-Rails processes (rake tasks, CLI tools) call it explicitly:
+
+```ruby
+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.
+
+## Admin UI Security
+
+The Admin UI is CSRF-protected out of the box (`protect_from_forgery with:
+:exception`) and 404s on unknown feature IDs instead of auto-creating
+features from user-controlled `params[:id]`.
+
+Authentication is **opt-in** — if `Magick::AdminUI.config.require_role` is
+left `nil` the UI is reachable by anyone who can hit its routes. Always set
+it behind your app's auth:
+
+```ruby
+Magick::AdminUI.configure do |c|
+  c.require_role = ->(controller) { controller.current_user&.admin? }
+end
+```
+
 ## Testing
 
 Use the testing helpers in your RSpec tests:

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

@@ -3,6 +3,13 @@
 module Magick
   module AdminUI
     class FeaturesController < ActionController::Base
+      # Inheriting ActionController::Base does NOT bring in CSRF protection.
+      # Include RequestForgeryProtection + explicit protect_from_forgery so
+      # cross-site form submissions cannot toggle flags behind a logged-in
+      # admin's back.
+      include ::ActionController::RequestForgeryProtection
+      protect_from_forgery with: :exception
+
       # Include route helpers so views can use magick_admin_ui.* helpers
       include Magick::AdminUI::Engine.routes.url_helpers
       layout 'application'
@@ -120,6 +127,10 @@ module Magick
       def update_targeting
         # Handle targeting updates from form
         targeting_params = params[:targeting] || {}
+        unless hash_like?(targeting_params)
+          redirect_to magick_admin_ui.feature_path(@feature.name), alert: 'Invalid targeting payload.'
+          return
+        end
 
         # Ensure we're using the registered feature instance
         feature_name = @feature.name.to_s
@@ -266,13 +277,18 @@ module Magick
 
         redirect_to magick_admin_ui.feature_path(@feature.name), notice: 'Targeting updated successfully'
       rescue StandardError => e
-        Rails.logger.error "Magick: Error updating targeting: #{e.message}\n#{e.backtrace.first(5).join("\n")}" if defined?(Rails)
-        redirect_to magick_admin_ui.feature_path(@feature.name), alert: "Error updating targeting: #{e.message}"
+        Rails.logger.error "Magick: Error updating targeting for #{@feature.name}: #{e.class}: #{e.message}\n#{e.backtrace.first(5).join("\n")}" if defined?(Rails)
+        redirect_to magick_admin_ui.feature_path(@feature.name), alert: 'Could not update targeting — see server logs for details.'
       end
 
       def update_variants
         variants_data = []
 
+        if params[:variants].present? && !hash_like?(params[:variants])
+          redirect_to magick_admin_ui.feature_path(@feature.name), alert: 'Invalid variants payload.'
+          return
+        end
+
         if params[:variants].present?
           params[:variants].each do |_index, variant_params|
             next if variant_params[:name].blank?
@@ -295,8 +311,8 @@ module Magick
 
         redirect_to magick_admin_ui.feature_path(@feature.name), notice: 'Variants updated successfully'
       rescue StandardError => e
-        Rails.logger.error "Magick: Error updating variants: #{e.message}" if defined?(Rails)
-        redirect_to magick_admin_ui.feature_path(@feature.name), alert: "Error updating variants: #{e.message}"
+        Rails.logger.error "Magick: Error updating variants for #{@feature.name}: #{e.class}: #{e.message}" if defined?(Rails)
+        redirect_to magick_admin_ui.feature_path(@feature.name), alert: 'Could not update variants — see server logs for details.'
       end
 
       private
@@ -313,13 +329,25 @@ module Magick
         end
       end
 
+      # A hash-like payload is either a raw Hash or an
+      # ActionController::Parameters (both respond to :each with key/value).
+      # Rejecting anything else lets us give a 400-style redirect instead of
+      # a 500 with a NoMethodError stack trace.
+      def hash_like?(obj)
+        obj.is_a?(Hash) || (defined?(ActionController::Parameters) && obj.is_a?(ActionController::Parameters))
+      end
+
       def set_feature
         feature_name = params[:id].to_s
-        @feature = Magick.features[feature_name] || Magick[feature_name]
-        redirect_to magick_admin_ui.features_path, alert: 'Feature not found' unless @feature
-
-        # Ensure we're working with the registered feature instance to keep state in sync
-        @feature = Magick.features[feature_name] if Magick.features.key?(feature_name)
+        # Do NOT fall back to Magick[feature_name] — that would lazily create
+        # and persist a brand-new feature from user-controlled input, letting
+        # an attacker (or even a stray crawler) pollute Redis/AR with arbitrary
+        # keys. Look up only registered features; 404 otherwise.
+        @feature = Magick.features[feature_name]
+        return if @feature
+
+        redirect_to magick_admin_ui.features_path, alert: 'Feature not found'
+        nil
       end
     end
   end

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

@@ -3,6 +3,9 @@
 module Magick
   module AdminUI
     class StatsController < ActionController::Base
+      include ::ActionController::RequestForgeryProtection
+      protect_from_forgery with: :exception
+
       include Magick::AdminUI::Engine.routes.url_helpers
       layout 'application'
 
@@ -13,8 +16,13 @@ module Magick
       end
 
       def show
-        @feature = Magick.features[params[:id].to_s] || Magick[params[:id]]
-        @stats = Magick.feature_stats(params[:id].to_sym) || {} if @feature
+        feature_name = params[:id].to_s
+        @feature = Magick.features[feature_name]
+        unless @feature
+          head :not_found
+          return
+        end
+        @stats = Magick.feature_stats(feature_name.to_sym) || {}
       end
     end
   end

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

@@ -32,3 +32,21 @@ Magick.configure do
   # Enable deprecation warnings in logs
   warn_on_deprecated enabled: true
 end
+
+# Admin UI configuration (optional).
+# The Admin UI is CSRF-protected and 404s on unknown feature IDs, BUT
+# authentication is opt-in — if you mount the engine without configuring
+# `require_role`, the UI will be reachable by anyone who can hit its routes.
+# Always wire it to your host app's auth layer:
+#
+# Magick::AdminUI.configure do |c|
+#   c.require_role = ->(controller) { controller.current_user&.admin? }
+#   c.available_roles = %w[admin manager]
+#   c.available_tags  = -> { Tag.pluck(:name) }
+# end
+
+# Graceful shutdown is handled automatically in Rails via an at_exit hook
+# wired by the Railtie. In long-running non-Rails processes (rake tasks,
+# CLI tools), call `Magick.shutdown!` explicitly before exit so the
+# Redis Pub/Sub subscriber and async metrics thread terminate cleanly.
+

data/lib/magick/adapters/base.rb

@@ -33,9 +33,13 @@ module Magick
         {}
       end
 
-      # Bulk set multiple keys for a feature in one call (override for efficiency)
-      def set_all_data(_feature_name, _data_hash)
-        # Default: no-op, subclasses override
+      # Bulk set multiple keys for a feature in one call.
+      # Subclasses MUST implement this — a no-op default silently drops
+      # bulk writes, which is why this used to cause hard-to-diagnose lost
+      # updates for custom adapters (audit P2-Co6).
+      def set_all_data(feature_name, data_hash)
+        raise NotImplementedError,
+              "#{self.class} must implement #set_all_data (feature=#{feature_name}, keys=#{data_hash.keys.inspect})"
       end
     end
   end

data/lib/magick/adapters/memory.rb

@@ -31,6 +31,7 @@ module Magick
 
       def set(feature_name, key, value)
         mutex.synchronize do
+          cleanup_expired_if_needed
           feature_name_str = feature_name.to_s
           store[feature_name_str] ||= {}
           store[feature_name_str][key.to_s] = serialize_value(value)
@@ -91,6 +92,7 @@ module Magick
       # Bulk set all data for a feature (used by preloading)
       def set_all_data(feature_name, data_hash)
         mutex.synchronize do
+          cleanup_expired_if_needed
           feature_name_str = feature_name.to_s
           store[feature_name_str] ||= {}
           data_hash.each do |key, value|

data/lib/magick/adapters/redis.rb

@@ -103,13 +103,24 @@ module Magick
 
       attr_reader :redis, :namespace
 
-      # Use SCAN instead of KEYS to avoid blocking Redis
+      # Use SCAN instead of KEYS to avoid blocking Redis.
+      # A mid-scan timeout would otherwise lose the cursor; retry once with
+      # exponential backoff before surfacing the error to the caller.
       def scan_keys
         pattern = "#{namespace}:*"
         keys = []
         cursor = '0'
+        retries = 0
         loop do
-          cursor, batch = redis.scan(cursor, match: pattern, count: 100)
+          begin
+            cursor, batch = redis.scan(cursor, match: pattern, count: 100)
+          rescue StandardError => e
+            raise if retries >= 1
+
+            retries += 1
+            sleep(0.05 * retries)
+            retry
+          end
           keys.concat(batch)
           break if cursor == '0'
         end

data/lib/magick/adapters/registry.rb

@@ -7,6 +7,12 @@ module Magick
 
       LOCAL_WRITE_TTL = 2.0 # seconds to ignore self-invalidation after a local write
 
+      # Accept only conservative feature identifiers coming off the wire.
+      # Anything outside this alphabet (newlines, spaces, Unicode punctuation,
+      # 200-char garbage) is a sign of a malformed or malicious publisher and
+      # must not be fed back into Magick.features[...] / feature.reload.
+      FEATURE_NAME_PATTERN = /\A[a-zA-Z0-9_\-.:]{1,120}\z/.freeze
+
       def initialize(memory_adapter, redis_adapter = nil, active_record_adapter: nil, circuit_breaker: nil,
                      async: false, primary: nil)
         @memory_adapter = memory_adapter
@@ -21,11 +27,54 @@ module Magick
         @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
+        @shutdown_mutex = Mutex.new
+        @owner_pid = Process.pid
         # Only start Pub/Sub subscriber if Redis is available
         # In memory-only mode, each process has isolated cache (no cross-process invalidation)
         start_cache_invalidation_subscriber if redis_adapter
       end
 
+      # Restart the Pub/Sub subscriber after a fork. The subscriber thread is
+      # not carried into child processes, so a worker inheriting a stale
+      # reference must re-create its own subscription. Safe to call on every
+      # request; it only does work when Process.pid changes.
+      def ensure_subscriber!
+        return if @owner_pid == Process.pid
+
+        @shutdown_mutex.synchronize do
+          return if @owner_pid == Process.pid
+
+          @subscriber_thread = nil
+          @subscriber = nil
+          @owner_pid = Process.pid
+          @stopping = false
+        end
+
+        start_cache_invalidation_subscriber if redis_adapter
+      end
+
+      # Gracefully terminate the Pub/Sub subscriber thread and its Redis connection.
+      # Without this, Ruby/Puma shutdown waits on the blocking `subscribe` call.
+      def shutdown(timeout: 5)
+        @shutdown_mutex.synchronize do
+          return if @stopping
+
+          @stopping = true
+        end
+
+        close_subscriber_connection(@subscriber)
+        terminate_subscriber_thread(@subscriber_thread, timeout)
+
+        @subscriber = nil
+        @subscriber_thread = nil
+        true
+      end
+
+      def stopping?
+        @stopping == true
+      end
+
       def get(feature_name, key)
         # Try memory first (fastest) - no Redis calls needed thanks to Pub/Sub invalidation
         value = memory_adapter.get(feature_name, key) if memory_adapter
@@ -76,11 +125,7 @@ module Magick
           end
 
           if @async && defined?(Thread)
-            Thread.new do
-              update_redis.call
-              # Publish AFTER Redis write so other processes read fresh data
-              publish_cache_invalidation(feature_name)
-            end
+            spawn_async_write(feature_name, update_redis)
           else
             update_redis.call
             publish_cache_invalidation(feature_name)
@@ -226,11 +271,7 @@ module Magick
           end
 
           if @async && defined?(Thread)
-            Thread.new do
-              update_redis.call
-              # Publish AFTER Redis write so other processes read fresh data
-              publish_cache_invalidation(feature_name)
-            end
+            spawn_async_write(feature_name, update_redis)
           else
             update_redis.call
             publish_cache_invalidation(feature_name)
@@ -288,11 +329,57 @@ module Magick
 
       attr_reader :memory_adapter, :redis_adapter, :active_record_adapter, :circuit_breaker
 
+      # Signal the subscribe loop to return, then close the connection so any
+      # retry/reconnect attempt fails fast instead of sleeping for 5s.
+      def close_subscriber_connection(subscriber)
+        return unless subscriber
+
+        begin
+          subscriber.unsubscribe(CACHE_INVALIDATION_CHANNEL)
+        rescue StandardError
+          # connection may already be dead; fall through to close/kill
+        end
+
+        begin
+          subscriber.close
+        rescue StandardError
+          # ignore: best-effort close
+        end
+      end
+
+      def terminate_subscriber_thread(thread, timeout)
+        return unless thread
+        return if thread.join(timeout)
+
+        thread.kill
+        thread.join(1) # give it a moment to actually unwind
+      end
+
+      # Fire-and-forget async Redis write. Wrapped so that a failure in the
+      # update or publish step is logged rather than silently killing the
+      # thread — Thread#abort_on_exception is false, which otherwise swallows
+      # the error completely.
+      def spawn_async_write(feature_name, update_redis)
+        thread = Thread.new do
+          update_redis.call
+          publish_cache_invalidation(feature_name)
+        rescue StandardError => e
+          warn "Magick: async Redis write failed for '#{Magick::LogSafe.sanitize(feature_name)}': #{e.class}: #{Magick::LogSafe.sanitize(e.message)}"
+        end
+        thread.name = "magick-async-write-#{feature_name}" if thread.respond_to?(:name=)
+        thread.abort_on_exception = false
+        thread
+      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)
         @reload_mutex.synchronize do
           @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.
+          cleanup_stale_tracking_entries
         end
       end
 
@@ -357,6 +444,16 @@ module Magick
             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).
@@ -408,7 +505,7 @@ module Magick
               end
 
               if defined?(Rails) && Rails.env.development?
-                warn "Magick: Error processing cache invalidation for '#{feature_name}': #{e.message}"
+                warn "Magick: Error processing cache invalidation for '#{Magick::LogSafe.sanitize(feature_name)}': #{Magick::LogSafe.sanitize(e.message)}"
               end
             end
           end
@@ -421,9 +518,13 @@ module Magick
                            (defined?(Rails) && Rails.env.test?)
           return if is_rspec_error
 
+          # Stop cleanly during app shutdown instead of sleeping + retrying,
+          # which would keep the process alive and delay termination.
+          return if @stopping
+
           warn "Cache invalidation subscriber error: #{e.message}" if defined?(Rails) && Rails.env.development?
           sleep 5
-          retry
+          retry unless @stopping
         end
         @subscriber_thread.abort_on_exception = false
       end

data/lib/magick/admin_ui/helpers.rb

@@ -4,28 +4,33 @@ module Magick
   module AdminUI
     module Helpers
       def self.feature_status_badge(status)
-        case status.to_sym
-        when :active
-          '<span class="badge badge-success">Active</span>'
-        when :deprecated
-          '<span class="badge badge-warning">Deprecated</span>'
-        when :inactive
-          '<span class="badge badge-danger">Inactive</span>'
+        klass = case status.to_sym
+                when :active then 'badge badge-success'
+                when :deprecated then 'badge badge-warning'
+                when :inactive then 'badge badge-danger'
+                else 'badge'
+                end
+        label = case status.to_sym
+                when :active then 'Active'
+                when :deprecated then 'Deprecated'
+                when :inactive then 'Inactive'
+                else 'Unknown'
+                end
+
+        if defined?(ActionController::Base)
+          ActionController::Base.helpers.content_tag(:span, label, class: klass)
         else
-          '<span class="badge">Unknown</span>'
+          # Fallback when Rails is not present. Label is a whitelisted literal.
+          "<span class=\"#{klass}\">#{label}</span>"
         end
       end
 
       def self.feature_type_label(type)
         case type.to_sym
-        when :boolean
-          'Boolean'
-        when :string
-          'String'
-        when :number
-          'Number'
-        else
-          type.to_s.capitalize
+        when :boolean then 'Boolean'
+        when :string then 'String'
+        when :number then 'Number'
+        else type.to_s.capitalize
         end
       end
     end

data/lib/magick/audit_log.rb

@@ -26,20 +26,27 @@ module Magick
       end
     end
 
-    def initialize(adapter = nil)
+    DEFAULT_MAX_ENTRIES = 10_000
+
+    def initialize(adapter = nil, max_entries: DEFAULT_MAX_ENTRIES)
       @adapter = adapter || default_adapter
       @logs = []
+      @max_entries = max_entries.to_i.positive? ? max_entries.to_i : DEFAULT_MAX_ENTRIES
       @mutex = Mutex.new
     end
 
+    attr_reader :max_entries
+
     def log(feature_name, action, user_id: nil, changes: {}, metadata: {})
       entry = Entry.new(feature_name, action, user_id: user_id, changes: changes, metadata: metadata)
       @mutex.synchronize do
         @logs << entry
+        # Cap in-memory ring; older entries fall out once we cross the limit.
+        # This keeps long-running processes from growing @logs unboundedly.
+        @logs.shift while @logs.size > @max_entries
         @adapter.append(entry) if @adapter.respond_to?(:append)
       end
 
-      # Rails 8+ event
       if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
         Magick::Rails::Events.audit_logged(feature_name, action: action, user_id: user_id, changes: changes, **metadata)
       end
@@ -48,9 +55,13 @@ module Magick
     end
 
     def entries(feature_name: nil, limit: 100)
-      result = @logs
-      result = result.select { |e| e.feature_name == feature_name.to_s } if feature_name
-      result.last(limit)
+      snapshot = @mutex.synchronize { @logs.dup }
+      snapshot = snapshot.select { |e| e.feature_name == feature_name.to_s } if feature_name
+      snapshot.last(limit)
+    end
+
+    def size
+      @mutex.synchronize { @logs.size }
     end
 
     private

data/lib/magick/config.rb

@@ -317,9 +317,29 @@ module Magick
       config
     end
 
+    # Load a Magick configuration DSL file by path.
+    #
+    # SECURITY: This method evaluates the file's contents as Ruby via
+    # instance_eval. Never pass a path derived from HTTP input, ENV
+    # variables, build artifacts, or any other untrusted source — doing so
+    # is remote code execution. Callers must guarantee the path points at a
+    # file that lives inside the project tree (typical use:
+    # Rails.root.join('config/features.rb')).
+    #
+    # The path is resolved with File.realpath and must be inside the
+    # current working directory. An explicit opt-in env var
+    # (MAGICK_ALLOW_CONFIG_EVAL=1) is required to load paths outside CWD.
     def self.load_from_file(file_path)
+      resolved = File.realpath(file_path)
+      allow_outside_cwd = ENV['MAGICK_ALLOW_CONFIG_EVAL'] == '1'
+      unless allow_outside_cwd || resolved.start_with?(Dir.pwd)
+        raise SecurityError,
+              "Refusing to load Magick config from outside the project tree: #{resolved}. " \
+              'Set MAGICK_ALLOW_CONFIG_EVAL=1 to override (only if you trust the file).'
+      end
+
       config = Config.new
-      config.instance_eval(File.read(file_path), file_path)
+      config.instance_eval(File.read(resolved), resolved)
       config.apply!
       config
     end

data/lib/magick/export_import.rb

@@ -4,12 +4,23 @@ require 'json'
 
 module Magick
   class ExportImport
+    # Hard cap on the number of features accepted by a single import call.
+    # Guards against DoS via an oversized payload and (combined with Admin UI
+    # auth) stops an attacker from using import as a flag-replacement
+    # primitive. Override with the MAGICK_MAX_IMPORT_FEATURES env var.
+    DEFAULT_MAX_IMPORT_FEATURES = 10_000
+
+    class ImportError < StandardError; end
+
+    def self.max_import_features
+      ENV.fetch('MAGICK_MAX_IMPORT_FEATURES', DEFAULT_MAX_IMPORT_FEATURES).to_i
+    end
+
     def self.export(features_hash)
       result = features_hash.map do |_name, feature|
         feature.to_h
       end
 
-      # Rails 8+ event
       if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
         Magick::Rails::Events.exported(format: :hash, feature_count: result.length)
       end
@@ -20,7 +31,6 @@ module Magick
     def self.export_json(features_hash)
       result = JSON.pretty_generate(export(features_hash))
 
-      # Rails 8+ event
       if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
         Magick::Rails::Events.exported(format: :json, feature_count: features_hash.length)
       end
@@ -31,54 +41,135 @@ module Magick
     def self.import(data, adapter_registry)
       features = {}
       data = JSON.parse(data) if data.is_a?(String)
+      list = Array(data)
 
-      Array(data).each do |feature_data|
-        name = feature_data['name'] || feature_data[:name]
-        next unless name
+      cap = max_import_features
+      if list.size > cap
+        raise ImportError,
+              "Magick.import: refused to import #{list.size} features; limit is #{cap}. " \
+              'Set MAGICK_MAX_IMPORT_FEATURES to override.'
+      end
 
-        feature = Feature.new(
-          name,
-          adapter_registry,
-          type: (feature_data['type'] || feature_data[:type] || :boolean).to_sym,
-          status: (feature_data['status'] || feature_data[:status] || :active).to_sym,
-          default_value: feature_data['default_value'] || feature_data[:default_value],
-          description: feature_data['description'] || feature_data[:description]
-        )
-
-        if feature_data['value'] || feature_data[:value]
-          feature.set_value(feature_data['value'] || feature_data[:value])
+      list.each do |feature_data|
+        unless feature_data.is_a?(Hash)
+          raise ImportError, "Magick.import: each feature payload must be a Hash, got #{feature_data.class}"
         end
 
-        # Import targeting
-        if feature_data['targeting'] || feature_data[:targeting]
-          targeting = feature_data['targeting'] || feature_data[:targeting]
-          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)
-              when :percentage_users
-                feature.enable_percentage_of_users(value)
-              when :percentage_requests
-                feature.enable_percentage_of_requests(value)
-              end
-            end
-          end
-        end
+        name = fetch(feature_data, :name)
+        next unless name
+
+        feature = build_feature(name, feature_data, adapter_registry)
+        apply_value(feature, feature_data)
+        apply_targeting(feature, fetch(feature_data, :targeting) || {})
+        apply_variants(feature, fetch(feature_data, :variants) || [])
+        apply_dependencies(feature, fetch(feature_data, :dependencies) || [])
 
         features[name.to_s] = feature
       end
 
-      # Rails 8+ event
       if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
         Magick::Rails::Events.imported(format: :json, feature_count: features.length)
       end
 
       features
     end
+
+    def self.fetch(hash, key)
+      # Must not use `||` — falsy legitimate values (false, 0, "") would
+      # silently fall through to the string-key lookup (and then to nil).
+      return hash[key] if hash.key?(key)
+
+      string_key = key.to_s
+      return hash[string_key] if hash.key?(string_key)
+
+      nil
+    end
+
+    def self.build_feature(name, feature_data, adapter_registry)
+      Feature.new(
+        name,
+        adapter_registry,
+        type: (fetch(feature_data, :type) || :boolean).to_sym,
+        status: (fetch(feature_data, :status) || :active).to_sym,
+        default_value: fetch(feature_data, :default_value),
+        description: fetch(feature_data, :description),
+        display_name: fetch(feature_data, :display_name),
+        group: fetch(feature_data, :group)
+      )
+    end
+
+    def self.apply_value(feature, feature_data)
+      value = fetch(feature_data, :value)
+      feature.set_value(value) if !value.nil? && !(value.is_a?(String) && value.empty?)
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/CyclomaticComplexity
+    def self.apply_targeting(feature, targeting)
+      targeting.each do |type, values|
+        case type.to_sym
+        when :user, :users
+          Array(values).each { |v| feature.enable_for_user(v) }
+        when :excluded_users
+          Array(values).each { |v| feature.exclude_user(v) }
+        when :group, :groups
+          Array(values).each { |v| feature.enable_for_group(v) }
+        when :excluded_groups
+          Array(values).each { |v| feature.exclude_group(v) }
+        when :role, :roles
+          Array(values).each { |v| feature.enable_for_role(v) }
+        when :excluded_roles
+          Array(values).each { |v| feature.exclude_role(v) }
+        when :tag, :tags
+          Array(values).each { |v| feature.enable_for_tag(v) }
+        when :excluded_tags
+          Array(values).each { |v| feature.exclude_tag(v) }
+        when :ip_address, :ip_addresses
+          feature.enable_for_ip_addresses(Array(values))
+        when :excluded_ip_addresses
+          feature.exclude_ip_addresses(Array(values))
+        when :percentage_users
+          feature.enable_percentage_of_users(values)
+        when :percentage_requests
+          feature.enable_percentage_of_requests(values)
+        when :date_range
+          range = values.is_a?(Hash) ? values.transform_keys(&:to_sym) : values
+          feature.enable_for_date_range(range[:start], range[:end]) if range.is_a?(Hash) && range[:start] && range[:end]
+        when :custom_attributes
+          apply_custom_attributes(feature, values)
+        end
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    def self.apply_custom_attributes(feature, values)
+      return unless values.is_a?(Hash)
+
+      values.each do |attr, rule|
+        rule_h = rule.is_a?(Hash) ? rule.transform_keys(&:to_sym) : {}
+        next unless rule_h[:values]
+
+        feature.enable_for_custom_attribute(attr, rule_h[:values], operator: (rule_h[:operator] || :equals).to_sym)
+      end
+    end
+
+    def self.apply_variants(feature, variants)
+      return unless feature.respond_to?(:add_variant)
+
+      Array(variants).each do |v|
+        h = v.is_a?(Hash) ? v.transform_keys(&:to_sym) : {}
+        next unless h[:name]
+
+        feature.add_variant(h[:name], weight: h[:weight], value: h[:value])
+      end
+    end
+
+    def self.apply_dependencies(feature, deps)
+      list = Array(deps).map(&:to_s)
+      return if list.empty?
+
+      feature.instance_variable_set(:@dependencies, list)
+    end
   end
 end

data/lib/magick/feature.rb

@@ -85,7 +85,7 @@ module Magick
         perf_metrics.record(name, 'enabled?', duration, success: false)
       end
       # Return false on any error (fail-safe)
-      warn "Magick: Error checking feature '#{name}': #{e.message}" if defined?(Rails) && Rails.env.development?
+      warn "Magick: Error checking feature '#{Magick::LogSafe.sanitize(name)}': #{Magick::LogSafe.sanitize(e.message)}" if defined?(Rails) && Rails.env.development?
       false
     end
 
@@ -152,7 +152,7 @@ module Magick
       end
     rescue StandardError => e
       # Return false on any error (fail-safe)
-      warn "Magick: Error in check_enabled for '#{name}': #{e.message}" if defined?(Rails) && Rails.env.development?
+      warn "Magick: Error in check_enabled for '#{Magick::LogSafe.sanitize(name)}': #{Magick::LogSafe.sanitize(e.message)}" if defined?(Rails) && Rails.env.development?
       false
     end
 
@@ -223,7 +223,7 @@ module Magick
       end
     rescue StandardError => e
       # Return default value on error (fail-safe)
-      warn "Magick: Error in get_value for '#{name}': #{e.message}" if defined?(Rails) && Rails.env.development?
+      warn "Magick: Error in get_value for '#{Magick::LogSafe.sanitize(name)}': #{Magick::LogSafe.sanitize(e.message)}" if defined?(Rails) && Rails.env.development?
       default_value
     end
 
@@ -310,7 +310,15 @@ module Magick
     end
 
     def exclude_ip_addresses(ip_addresses)
-      enable_targeting(:excluded_ip_addresses, Array(ip_addresses))
+      # excluded_ip_addresses is stored as a flat Array of strings; bypass the
+      # generic enable_targeting path whose "array type" branch stringifies the
+      # incoming array into a single element.
+      @targeting[:excluded_ip_addresses] ||= []
+      Array(ip_addresses).each do |ip|
+        str = ip.to_s
+        @targeting[:excluded_ip_addresses] << str unless @targeting[:excluded_ip_addresses].include?(str)
+      end
+      save_targeting
       true
     end
 
@@ -370,7 +378,15 @@ module Magick
     end
 
     def enable_for_ip_addresses(ip_addresses)
-      enable_targeting(:ip_address, Array(ip_addresses))
+      # ip_address is stored as a flat Array of strings; bypass the generic
+      # enable_targeting path whose "array type" branch stringifies the
+      # incoming array into a single '["x.y.z"]' entry.
+      @targeting[:ip_address] ||= []
+      Array(ip_addresses).each do |ip|
+        str = ip.to_s
+        @targeting[:ip_address] << str unless @targeting[:ip_address].include?(str)
+      end
+      save_targeting
       true
     end
 
@@ -645,15 +661,31 @@ module Magick
       {
         name: name,
         display_name: display_name,
+        group: group,
         type: type,
         status: status,
         value: stored_value,
         default_value: default_value,
         description: description,
-        targeting: targeting
+        targeting: targeting,
+        dependencies: (@dependencies || []).dup,
+        variants: variants_for_export
       }
     end
 
+    def variants_for_export
+      return [] unless defined?(Magick::FeatureVariant)
+
+      raw = @variants || []
+      raw.map do |v|
+        if v.is_a?(Magick::FeatureVariant)
+          { name: v.name, weight: v.weight, value: v.value }
+        else
+          v
+        end
+      end
+    end
+
     def save_targeting
       # Save targeting to adapter (this updates memory synchronously, then Redis/AR)
       # The set method already publishes cache invalidation to other processes via Pub/Sub

data/lib/magick/log_safe.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Magick
+  # Sanitize strings before they go into logs / warnings.
+  # Two concerns:
+  #   1) Newlines in a user-influenced string (feature name, exception
+  #      message) let an attacker forge log entries ("log injection").
+  #   2) A long payload can flood a log pipeline.
+  # `LogSafe.sanitize` returns a single line at most 256 chars, control
+  # characters replaced with spaces.
+  module LogSafe
+    MAX_LEN = 256
+    CONTROL_CHARS = /[\r\n\t\e\u0000-\u001f\u007f]/.freeze
+
+    def self.sanitize(value, max: MAX_LEN)
+      str = value.to_s.dup
+      str.gsub!(CONTROL_CHARS, ' ')
+      str = str[0, max] if str.length > max
+      str
+    end
+  end
+end

data/lib/magick/performance_metrics.rb

@@ -2,6 +2,8 @@
 
 module Magick
   class PerformanceMetrics
+    METRICS_RING_CAP = 1_000
+
     class Metric
       attr_reader :feature_name, :operation, :duration, :timestamp, :success
 
@@ -45,7 +47,26 @@ module Magick
       @async_queue = Queue.new
       @async_thread = nil
       @async_enabled = true # Enable async by default for performance
+      @owner_pid = Process.pid
+      start_async_processor
+    end
+
+    # Restart the async processor after a fork. Child processes inherit a dead
+    # thread reference + a queue that was populated in the parent; both must
+    # be recreated. The inherited thread (if alive in the parent's address
+    # space at fork time) is killed so it cannot keep polling a detached queue.
+    def ensure_async_processor!
+      return if @owner_pid == Process.pid
+
+      stale_thread = @async_thread
+      stale_queue = @async_queue
+      @async_queue = Queue.new
+      @async_thread = nil
+      @owner_pid = Process.pid
       start_async_processor
+
+      stale_queue&.close if stale_queue.respond_to?(:close)
+      stale_thread&.kill
     end
 
     # Public accessor for redis_enabled
@@ -74,8 +95,9 @@ module Magick
       pending_count = nil
       total_pending = nil
       @mutex.synchronize do
-        # Only create Metric object if we're keeping metrics in memory
-        if @metrics.length < 1000
+        # Pre-insert cap: construct + append only when there is room.
+        # Keeps @metrics bounded at METRICS_RING_CAP under any load.
+        if @metrics.length < METRICS_RING_CAP
           metric = Metric.new(feature_name_str, operation_str, duration, success: success)
           @metrics << metric
         end
@@ -83,8 +105,6 @@ module Magick
         @pending_updates[feature_name_str] += 1
         pending_count = @pending_updates[feature_name_str]
         total_pending = @pending_updates.values.sum
-        # Keep only last 1000 metrics (as a safety limit)
-        @metrics.shift if @metrics.length > 1000
       end
 
       # Rails 8+ event for usage tracking (cached check)

data/lib/magick/rails/railtie.rb

@@ -119,12 +119,29 @@ if defined?(Rails)
         config.to_prepare do
           RequestStore.store[:magick_features] ||= {} if defined?(RequestStore)
 
+          # Restart background threads after Puma fork. ensure_*! is a no-op
+          # when Process.pid matches the owner pid, so it is cheap to call.
+          registry = Magick.adapter_registry
+          registry.ensure_subscriber! if registry.respond_to?(:ensure_subscriber!)
+          Magick.performance_metrics&.ensure_async_processor!
+
           # Final check: ensure Redis tracking is enabled (runs on every request in development)
           # This is the absolute last chance to enable it
           if Magick.performance_metrics && Magick.adapter_registry.is_a?(Adapters::Registry) && Magick.adapter_registry.redis_available? && !Magick.performance_metrics.redis_enabled
             Magick.performance_metrics.enable_redis_tracking(enable: true)
           end
         end
+
+        # Terminate the Pub/Sub subscriber + async metrics thread on process exit.
+        # Without this, Ruby waits on the blocking `Redis#subscribe` call inside
+        # the subscriber thread and Puma/Rails shutdown stalls.
+        initializer 'magick.shutdown_hook' do
+          at_exit do
+            Magick.shutdown!
+          rescue StandardError
+            # Best-effort: never raise from an at_exit handler.
+          end
+        end
       end
     end
 

data/lib/magick/version.rb

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

data/lib/magick/versioning.rb

@@ -30,19 +30,21 @@ module Magick
 
     def save_version(feature_name, version: nil, created_by: nil)
       feature = Magick.features[feature_name.to_s] || Magick[feature_name]
-      version ||= next_version(feature_name)
-      version_data = Version.new(version, feature.to_h, created_by: created_by)
-
-      @mutex.synchronize do
-        @versions[feature_name.to_s] ||= []
-        @versions[feature_name.to_s] << version_data
-        # Store in adapter
-        @adapter_registry.set(feature_name, "version_#{version}", version_data.to_h)
+      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
 
-      # Rails 8+ event
       if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
-        Magick::Rails::Events.version_saved(feature_name, version: version, created_by: created_by)
+        Magick::Rails::Events.version_saved(feature_name, version: version_data.version, created_by: created_by)
       end
 
       version_data
@@ -83,14 +85,16 @@ module Magick
     end
 
     def get_versions(feature_name)
-      @versions[feature_name.to_s] || []
+      @mutex.synchronize { (@versions[feature_name.to_s] || []).dup }
     end
 
     private
 
     def next_version(feature_name)
-      versions = get_versions(feature_name)
-      versions.empty? ? 1 : versions.last.version + 1
+      @mutex.synchronize do
+        list = @versions[feature_name.to_s] || []
+        list.empty? ? 1 : list.last.version + 1
+      end
     end
   end
 end

data/lib/magick.rb

@@ -18,8 +18,13 @@ require_relative 'magick/targeting/group'
 require_relative 'magick/targeting/role'
 require_relative 'magick/targeting/percentage'
 require_relative 'magick/targeting/request_percentage'
+require_relative 'magick/targeting/date_range'
+require_relative 'magick/targeting/ip_address'
+require_relative 'magick/targeting/custom_attribute'
+require_relative 'magick/targeting/complex'
 require_relative 'magick/errors'
 
+require_relative 'magick/log_safe'
 require_relative 'magick/audit_log'
 require_relative 'magick/performance_metrics'
 require_relative 'magick/export_import'
@@ -114,13 +119,22 @@ module Magick
       features[feature_name.to_s] || Feature.new(feature_name, adapter_registry || default_adapter_registry)
     end
 
+    # Mutex that guards writes to @features. Reads are lock-free by design:
+    # register_feature swaps the @features reference to a NEW hash via
+    # copy-on-write, so a concurrent iterator keeps its own snapshot and
+    # never sees "can't add a new key into hash during iteration".
+    FEATURES_MUTEX = Mutex.new
+    private_constant :FEATURES_MUTEX
+
     def features
       @features ||= {}
     end
 
     def register_feature(name, **options)
       feature = Feature.new(name, adapter_registry || default_adapter_registry, **options)
-      features[name.to_s] = feature
+      FEATURES_MUTEX.synchronize do
+        @features = (@features || {}).merge(name.to_s => feature)
+      end
       feature
     end
 
@@ -193,7 +207,9 @@ module Magick
 
     def import(data, format: :json)
       imported = ExportImport.import(data, adapter_registry || default_adapter_registry)
-      imported.each { |name, feature| features[name] = feature }
+      FEATURES_MUTEX.synchronize do
+        @features = (@features || {}).merge(imported)
+      end
       imported
     end
 
@@ -259,12 +275,24 @@ module Magick
     end
 
     def reset!
+      safely_shutdown(@adapter_registry) { |r| r.shutdown }
+      safely_shutdown(@default_adapter_registry) { |r| r.shutdown }
       @features = {}
       @adapter_registry = nil
       @default_adapter = nil
+      @default_adapter_registry = nil
       @performance_metrics&.clear!
     end
 
+    # Gracefully terminate background threads (Redis Pub/Sub subscriber,
+    # async metrics processor) so the host process can exit promptly.
+    # Intended for use in Rails shutdown hooks, `at_exit`, or tests.
+    def shutdown!(timeout: 5)
+      safely_shutdown(@adapter_registry) { |r| r.shutdown(timeout: timeout) }
+      safely_shutdown(@performance_metrics, &:stop_async_processor)
+      true
+    end
+
     # Get default adapter registry (public method for use by other classes)
     def default_adapter_registry
       @default_adapter_registry ||= begin
@@ -279,5 +307,15 @@ module Magick
     end
 
     private
+
+    # Run a cleanup action on a collaborator, swallowing errors so that
+    # shutdown hooks (at_exit, Rails) never raise.
+    def safely_shutdown(collaborator)
+      return unless collaborator
+
+      yield(collaborator)
+    rescue StandardError
+      # Best-effort: termination paths must not raise.
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: magick-feature-flags
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.1
 platform: ruby
 authors:
 - Andrew Lobanov
@@ -130,6 +130,7 @@ files:
 - lib/magick/feature.rb
 - lib/magick/feature_dependency.rb
 - lib/magick/feature_variant.rb
+- lib/magick/log_safe.rb
 - lib/magick/performance_metrics.rb
 - lib/magick/rails.rb
 - lib/magick/rails/event_subscriber.rb