magick-feature-flags 1.3.0 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 046dc5815e415705073eff7b3619c90bfd09a4af59b74d4116a3b2c206d5572e
-  data.tar.gz: 97bd2be3b303a73fa464c87ebbc6456098003601d236072c10e9a483e52c50b2
+  metadata.gz: 58eabf5855bcd4578d09090c65cc5b8d1b33ba2caa38ae7dd85bf7ecebb76047
+  data.tar.gz: e57e675ff58e913e60ef883b4dd8078087c7575ef5ced4355c8811bb15bf2dd3
 SHA512:
-  metadata.gz: 85d499e307729dfd4742ec0535f5edde63fb5dc2706ee8b1189dd63f8ed7f9c8c6d7a784d9a7f59e988f394fb92f41acc84c176a9544fb417c892586dd6444f2
-  data.tar.gz: 589515a83297e0d3ce02332afa309741533f1cf91fa556044b9a1f4f63a2d327248eba80c1727baa08ed5ed476db401530ddd21645eab3d7028624f97f6ee204
+  metadata.gz: 3fdaf5955fcf00d83047ff4ed785476b91b89e9d53ad80d890459e77134cf974cfe53a204060e471c491f133cd4d88f88e0f91813e042e5bf311821e09d804ea
+  data.tar.gz: d09483c77bb6af18a7f24565366d08e28a725c95d741c8cdcbf0ae3abcd17d8c3e0626942668a41f9041120a786f0463d35567c4ccfaaca3f56826f2888aa682

data/README.md

@@ -467,6 +467,32 @@ class CheckoutController < ApplicationController
 end
 ```
 
+**Experiments without a user (anonymous visitors):**
+
+For flows where there's no authenticated user yet (e.g., registration, landing pages), use any stable identifier as `user_id` — a session ID or a tracking cookie:
+
+```ruby
+class RegistrationController < ApplicationController
+  def new
+    cookies[:visitor_id] ||= SecureRandom.uuid
+    @variant = Magick.variant(:registration_flow, user_id: cookies[:visitor_id])
+  end
+end
+```
+
+The hashing just needs a consistent string. As long as the same visitor sends the same identifier, they get the same variant every time.
+
+**Safe to call on non-existent experiments:**
+
+```ruby
+Magick.variant(:nonexistent, user_id: 123)  # => nil
+Magick.variant_value(:nonexistent, user_id: 123)  # => nil
+```
+
+**Important — changing weights may shift users:**
+
+You can change variant weights at any time via the Admin UI or code, and changes take effect immediately across all adapters. However, changing weights alters the bucket boundaries, which means some users may be reassigned to a different variant after the update. Magick does not persist individual user-to-variant assignments — assignment is computed on the fly from the hash. If your experiment requires that users never shift variants mid-experiment, you should persist the assignment externally (e.g., store `user_id → variant` in a database table on first exposure).
+
 **How it works:**
 - Variants are assigned using a deterministic MD5 hash of `feature_name + user_id`
 - The same user always gets the same variant across sessions and requests

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

@@ -80,8 +80,11 @@ module Magick
       end
 
       def enable
-        @feature.enable
-        redirect_to magick_admin_ui.features_path, notice: 'Feature enabled'
+        if @feature.enable
+          redirect_to magick_admin_ui.features_path, notice: 'Feature enabled'
+        else
+          redirect_to magick_admin_ui.feature_path(@feature.name), alert: 'Cannot enable feature — its dependencies must be enabled first'
+        end
       end
 
       def disable

data/lib/magick/adapters/registry.rb

@@ -21,11 +21,34 @@ 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
         # 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
 
+      # 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
@@ -288,6 +311,32 @@ 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
+
       # 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)
@@ -421,9 +470,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/feature.rb

@@ -516,20 +516,16 @@ module Magick
     end
 
     def enable(user_id: nil)
-      # Check if this feature is a dependency of any disabled features
-      # If a main feature that depends on this feature is disabled, prevent enabling this dependency
-      # Dependencies cannot be enabled until the main feature is enabled
-      dependent_features = find_dependent_features
-      disabled_dependents = dependent_features.select do |dep_feature_name|
-        dep_feature = Magick.features[dep_feature_name.to_s] || Magick[dep_feature_name]
-        # Check if the dependent feature (main feature) is disabled
-        dep_feature && !dep_feature.enabled?
-      end
+      # Check that all of this feature's own dependencies are enabled
+      # e.g. if checkout depends on payments, checkout can't be enabled until payments is
+      deps = @dependencies || []
+      unless deps.empty?
+        disabled_deps = deps.select do |dep_name|
+          dep_feature = Magick.features[dep_name.to_s] || Magick[dep_name]
+          dep_feature && !dep_feature.enabled?
+        end
 
-      unless disabled_dependents.empty?
-        # Return false if any main feature that depends on this feature is disabled
-        # This prevents enabling a dependency when the main feature is disabled
-        return false
+        return false unless disabled_deps.empty?
       end
 
       # Clear all targeting to enable globally
@@ -988,13 +984,12 @@ module Magick
     end
 
     def disable_dependent_features(user_id: nil)
-      # Cascade-disable this feature's own dependencies (downstream sub-features).
-      # e.g. if A depends on B, disabling A also disables B.
-      # But disabling B does NOT cascade up to A.
-      deps = @dependencies || []
-      return if deps.empty?
+      # Cascade-disable features that depend ON this feature.
+      # e.g. if checkout depends on payments, disabling payments also disables checkout.
+      dependents = find_dependent_features
+      return if dependents.empty?
 
-      deps.each do |dep_name|
+      dependents.each do |dep_name|
         dep_feature = Magick.features[dep_name.to_s] || Magick[dep_name]
         next unless dep_feature
 

data/lib/magick/rails/railtie.rb

@@ -125,6 +125,17 @@ if defined?(Rails)
             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.0'
+  VERSION = '1.3.2'
 end

data/lib/magick.rb

@@ -265,6 +265,15 @@ module Magick
       @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 +288,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.0
+  version: 1.3.2
 platform: ruby
 authors:
 - Andrew Lobanov