magick-feature-flags 0.7.0

data/lib/magick/adapters/registry.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Magick
+  module Adapters
+    class Registry
+      CACHE_INVALIDATION_CHANNEL = 'magick:cache:invalidate'.freeze
+
+      def initialize(memory_adapter, redis_adapter = nil, circuit_breaker: nil, async: false)
+        @memory_adapter = memory_adapter
+        @redis_adapter = redis_adapter
+        @circuit_breaker = circuit_breaker || Magick::CircuitBreaker.new
+        @async = async
+        @subscriber_thread = nil
+        @subscriber = nil
+        # 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
+
+      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)
+        return value unless value.nil?
+
+        # Fall back to Redis if available
+        if redis_adapter
+          begin
+            value = redis_adapter.get(feature_name, key)
+            # Update memory cache if found in Redis
+            memory_adapter.set(feature_name, key, value) if value
+            return value
+          rescue AdapterError
+            # Redis failed, return nil
+            nil
+          end
+        end
+
+        nil
+      end
+
+      def set(feature_name, key, value)
+        # Update memory first (always synchronous)
+        memory_adapter.set(feature_name, key, value)
+
+        # Update Redis if available
+        if redis_adapter
+          update_redis = proc do
+            circuit_breaker.call do
+              redis_adapter.set(feature_name, key, value)
+              # Publish cache invalidation message to notify other processes
+              publish_cache_invalidation(feature_name)
+            end
+          rescue AdapterError => e
+            # Log error but don't fail - memory is updated
+            warn "Failed to update Redis: #{e.message}" if defined?(Rails) && Rails.env.development?
+          end
+
+          if @async && defined?(Thread)
+            Thread.new { update_redis.call }
+          else
+            update_redis.call
+          end
+        end
+      end
+
+      def delete(feature_name)
+        memory_adapter.delete(feature_name)
+        if redis_adapter
+          begin
+            redis_adapter.delete(feature_name)
+            # Publish cache invalidation message
+            publish_cache_invalidation(feature_name)
+          rescue AdapterError
+            # Continue even if Redis fails
+          end
+        end
+      end
+
+      def exists?(feature_name)
+        memory_adapter.exists?(feature_name) || (redis_adapter&.exists?(feature_name) == true)
+      end
+
+      def all_features
+        memory_features = memory_adapter.all_features
+        redis_features = redis_adapter&.all_features || []
+        (memory_features + redis_features).uniq
+      end
+
+      private
+
+      attr_reader :memory_adapter, :redis_adapter, :circuit_breaker
+
+      # Publish cache invalidation message to Redis Pub/Sub
+      def publish_cache_invalidation(feature_name)
+        return unless redis_adapter
+
+        begin
+          redis_client = redis_adapter.instance_variable_get(:@redis)
+          redis_client&.publish(CACHE_INVALIDATION_CHANNEL, feature_name.to_s)
+        rescue StandardError => e
+          # Silently fail - cache invalidation is best effort
+          warn "Failed to publish cache invalidation: #{e.message}" if defined?(Rails) && Rails.env.development?
+        end
+      end
+
+      # Start a background thread to listen for cache invalidation messages
+      def start_cache_invalidation_subscriber
+        return unless redis_adapter && defined?(Thread)
+
+        @subscriber_thread = Thread.new do
+          begin
+            redis_client = redis_adapter.instance_variable_get(:@redis)
+            return unless redis_client
+
+            @subscriber = redis_client.dup
+            @subscriber.subscribe(CACHE_INVALIDATION_CHANNEL) do |on|
+              on.message do |_channel, feature_name|
+                # Invalidate memory cache for this feature
+                memory_adapter.delete(feature_name)
+              end
+            end
+          rescue StandardError => e
+            # If subscription fails, log and retry after a delay
+            warn "Cache invalidation subscriber error: #{e.message}" if defined?(Rails) && Rails.env.development?
+            sleep 5
+            retry
+          end
+        end
+        @subscriber_thread.abort_on_exception = false
+      end
+    end
+  end
+end

data/lib/magick/audit_log.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Magick
+  class AuditLog
+    class Entry
+      attr_reader :feature_name, :action, :user_id, :timestamp, :changes, :metadata
+
+      def initialize(feature_name, action, user_id: nil, changes: {}, metadata: {})
+        @feature_name = feature_name.to_s
+        @action = action.to_s
+        @user_id = user_id
+        @timestamp = Time.now
+        @changes = changes
+        @metadata = metadata
+      end
+
+      def to_h
+        {
+          feature_name: feature_name,
+          action: action,
+          user_id: user_id,
+          timestamp: timestamp.iso8601,
+          changes: changes,
+          metadata: metadata
+        }
+      end
+    end
+
+    def initialize(adapter = nil)
+      @adapter = adapter || default_adapter
+      @logs = []
+      @mutex = Mutex.new
+    end
+
+    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
+        @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
+
+      entry
+    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)
+    end
+
+    private
+
+    def default_adapter
+      # Default to in-memory storage
+      Class.new do
+        def append(_entry); end
+      end.new
+    end
+  end
+end

data/lib/magick/circuit_breaker.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Magick
+  class CircuitBreaker
+    DEFAULT_FAILURE_THRESHOLD = 5
+    DEFAULT_TIMEOUT = 60
+
+    attr_reader :failure_count, :last_failure_time, :state
+
+    def initialize(failure_threshold: DEFAULT_FAILURE_THRESHOLD, timeout: DEFAULT_TIMEOUT)
+      @failure_threshold = failure_threshold
+      @timeout = timeout
+      @failure_count = 0
+      @last_failure_time = nil
+      @state = :closed
+      @mutex = Mutex.new
+    end
+
+    def call
+      return false if open?
+
+      begin
+        result = yield
+        record_success
+        result
+      rescue StandardError => e
+        record_failure
+        raise e
+      end
+    end
+
+    def open?
+      @mutex.synchronize do
+        if @state == :open
+          if Time.now.to_i - @last_failure_time.to_i > @timeout
+            @state = :half_open
+            @failure_count = 0
+            false
+          else
+            true
+          end
+        else
+          false
+        end
+      end
+    end
+
+    private
+
+    def record_success
+      @mutex.synchronize do
+        @failure_count = 0
+        @state = :closed if @state == :half_open
+      end
+    end
+
+    def record_failure
+      @mutex.synchronize do
+        @failure_count += 1
+        @last_failure_time = Time.now
+        @state = :open if @failure_count >= @failure_threshold
+      end
+    end
+  end
+end

data/lib/magick/config.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Magick
+  class Config
+    attr_accessor :adapter_registry, :performance_metrics, :audit_log, :versioning
+    attr_accessor :warn_on_deprecated, :async_updates, :memory_ttl, :circuit_breaker_threshold
+    attr_accessor :circuit_breaker_timeout, :redis_url, :redis_namespace, :environment
+
+    def initialize
+      @warn_on_deprecated = false
+      @async_updates = false
+      @memory_ttl = 3600 # 1 hour
+      @circuit_breaker_threshold = 5
+      @circuit_breaker_timeout = 60
+      @redis_namespace = 'magick:features'
+      @environment = defined?(Rails) ? Rails.env.to_s : 'development'
+    end
+
+    # DSL methods for configuration
+    def adapter(type, **options, &block)
+      case type.to_sym
+      when :memory
+        configure_memory_adapter(**options)
+      when :redis
+        configure_redis_adapter(**options)
+      when :registry
+        if block_given?
+          instance_eval(&block)
+          configure_registry_adapter
+        else
+          configure_registry_adapter(**options)
+        end
+      else
+        raise ArgumentError, "Unknown adapter type: #{type}"
+      end
+    end
+
+    def memory(**options)
+      configure_memory_adapter(**options)
+    end
+
+    def redis(url: nil, namespace: nil, **options)
+      @redis_url = url if url
+      @redis_namespace = namespace if namespace
+      configure_redis_adapter(url: url, namespace: namespace, **options)
+    end
+
+    def performance_metrics(enabled: true, **options)
+      if enabled
+        @performance_metrics = PerformanceMetrics.new
+      else
+        @performance_metrics = nil
+      end
+    end
+
+    def audit_log(enabled: true, adapter: nil)
+      if enabled
+        @audit_log = adapter ? AuditLog.new(adapter) : AuditLog.new
+      else
+        @audit_log = nil
+      end
+    end
+
+    def versioning(enabled: true)
+      if enabled
+        @versioning = Versioning.new(adapter_registry || default_adapter_registry)
+      else
+        @versioning = nil
+      end
+    end
+
+    def circuit_breaker(threshold: nil, timeout: nil)
+      @circuit_breaker_threshold = threshold if threshold
+      @circuit_breaker_timeout = timeout if timeout
+    end
+
+    def async_updates(enabled: true)
+      @async_updates = enabled
+    end
+
+    def memory_ttl(seconds)
+      @memory_ttl = seconds
+    end
+
+    def warn_on_deprecated(enabled: true)
+      @warn_on_deprecated = enabled
+    end
+
+    def environment(name)
+      @environment = name.to_s
+    end
+
+    def apply!
+      # Apply configuration to Magick module
+      Magick.adapter_registry = adapter_registry if adapter_registry
+      Magick.performance_metrics = performance_metrics if performance_metrics
+      Magick.audit_log = audit_log if audit_log
+      Magick.versioning = versioning if versioning
+      Magick.warn_on_deprecated = warn_on_deprecated
+    end
+
+    private
+
+    def configure_memory_adapter(ttl: nil)
+      ttl ||= @memory_ttl
+      adapter = Adapters::Memory.new
+      # Set default TTL by updating the adapter's default_ttl
+      adapter.instance_variable_set(:@default_ttl, ttl) if ttl
+      adapter
+    end
+
+    def configure_redis_adapter(url: nil, namespace: nil, client: nil)
+      return nil unless defined?(Redis)
+
+      url ||= @redis_url
+      namespace ||= @redis_namespace
+
+      redis_client = client || begin
+        if url
+          ::Redis.new(url: url)
+        else
+          ::Redis.new
+        end
+      rescue StandardError
+        nil
+      end
+
+      return nil unless redis_client
+
+      adapter = Adapters::Redis.new(redis_client)
+      adapter.instance_variable_set(:@namespace, namespace) if namespace
+      adapter
+    end
+
+    def configure_registry_adapter(memory: nil, redis: nil, async: nil, circuit_breaker: nil)
+      memory_adapter = memory || configure_memory_adapter
+      redis_adapter = redis || configure_redis_adapter
+
+      cb = circuit_breaker || CircuitBreaker.new(
+        failure_threshold: @circuit_breaker_threshold,
+        timeout: @circuit_breaker_timeout
+      )
+
+      async_enabled = async.nil? ? @async_updates : async
+
+      @adapter_registry = Adapters::Registry.new(
+        memory_adapter,
+        redis_adapter,
+        circuit_breaker: cb,
+        async: async_enabled
+      )
+    end
+
+    def default_adapter_registry
+      @default_adapter_registry ||= begin
+        memory_adapter = Adapters::Memory.new
+        redis_adapter = configure_redis_adapter
+        Adapters::Registry.new(memory_adapter, redis_adapter)
+      end
+    end
+  end
+
+  # DSL for configuration
+  module ConfigDSL
+    def self.configure(&block)
+      config = Config.new
+      config.instance_eval(&block)
+      config.apply!
+      config
+    end
+
+    def self.load_from_file(file_path)
+      config = Config.new
+      config.instance_eval(File.read(file_path), file_path)
+      config.apply!
+      config
+    end
+  end
+end

data/lib/magick/dsl.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Magick
+  module DSL
+    # Feature definition DSL methods
+    def feature(name, **options)
+      Magick.register_feature(name, **options)
+    end
+
+    def boolean_feature(name, default: false, **options)
+      Magick.register_feature(name, type: :boolean, default_value: default, **options)
+    end
+
+    def string_feature(name, default: '', **options)
+      Magick.register_feature(name, type: :string, default_value: default, **options)
+    end
+
+    def number_feature(name, default: 0, **options)
+      Magick.register_feature(name, type: :number, default_value: default, **options)
+    end
+
+    # Targeting DSL methods
+    def enable_for_user(feature_name, user_id)
+      Magick[feature_name].enable_for_user(user_id)
+    end
+
+    def enable_for_group(feature_name, group_name)
+      Magick[feature_name].enable_for_group(group_name)
+    end
+
+    def enable_for_role(feature_name, role_name)
+      Magick[feature_name].enable_for_role(role_name)
+    end
+
+    def enable_percentage(feature_name, percentage, type: :users)
+      feature = Magick[feature_name]
+      case type
+      when :users
+        feature.enable_percentage_of_users(percentage)
+      when :requests
+        feature.enable_percentage_of_requests(percentage)
+      end
+    end
+
+    def enable_for_date_range(feature_name, start_date, end_date)
+      Magick[feature_name].enable_for_date_range(start_date, end_date)
+    end
+
+    def enable_for_ip_addresses(feature_name, *ip_addresses)
+      Magick[feature_name].enable_for_ip_addresses(ip_addresses)
+    end
+
+    def enable_for_custom_attribute(feature_name, attribute_name, values, operator: :equals)
+      Magick[feature_name].enable_for_custom_attribute(attribute_name, values, operator: operator)
+    end
+
+    def set_variants(feature_name, variants)
+      Magick[feature_name].set_variants(variants)
+    end
+
+    def add_dependency(feature_name, dependency_name)
+      Magick[feature_name].add_dependency(dependency_name)
+    end
+
+    # Enable/disable features globally
+    def enable_feature(feature_name, user_id: nil)
+      Magick[feature_name].enable(user_id: user_id)
+    end
+
+    def disable_feature(feature_name, user_id: nil)
+      Magick[feature_name].disable(user_id: user_id)
+    end
+  end
+end
+
+# Make DSL methods available at top level for config/features.rb and config/initializers/features.rb
+# Include into Object so methods are available as instance methods on main (top-level context)
+Object.class_eval do
+  include Magick::DSL unless included_modules.include?(Magick::DSL)
+end

data/lib/magick/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Magick
+  class Error < StandardError; end
+  class FeatureNotFoundError < Error; end
+  class InvalidFeatureTypeError < Error; end
+  class InvalidFeatureValueError < Error; end
+  class AdapterError < Error; end
+end

data/lib/magick/export_import.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Magick
+  class ExportImport
+    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
+
+      result
+    end
+
+    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
+
+      result
+    end
+
+    def self.import(data, adapter_registry)
+      features = {}
+      data = JSON.parse(data) if data.is_a?(String)
+
+      Array(data).each do |feature_data|
+        name = feature_data['name'] || feature_data[:name]
+        next unless name
+
+        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]
+        )
+
+        feature.set_value(feature_data['value'] || feature_data[:value]) if feature_data['value'] || feature_data[:value]
+
+        # 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
+
+        features[name.to_s] = feature
+      end
+
+      # Rails 8+ event
+      if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
+        Magick::Rails::Events.imported(format: format, feature_count: features.length)
+      end
+
+      features
+    end
+  end
+end