magick-feature-flags 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 26705304fe361a52c069dde57f271991a8e108bd83b812754928551fe8eb1c50
+  data.tar.gz: 025b53d5898a675b1d0dca7b66244ced692ad51fa1036ab0c5bdc1df929184e4
+SHA512:
+  metadata.gz: 2f88df6bd3c9e236bb7a3cbffefa4b6a38e14b5d0d4ae3a85840c0473375c74bc0118c85d9646f2567e5615e581124d652ecd742c7ad89b70127cd443bae4f76
+  data.tar.gz: 26d30eb262dbd89fc78c3df40d46f8bd5f176ffd59720302bc9054f458cb4123de51d6b01051e8ad5e9eb3944bf4c430ddf1bf3f3f264369f3eb2764cdcf0d08

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrew Lobanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,363 @@
+# Magick
+
+A performant and memory-efficient feature toggle gem for Ruby and Rails applications.
+
+## Features
+
+- **Multiple Feature Types**: Boolean, string, and number feature flags
+- **Flexible Targeting**: Enable features for specific users, groups, roles, or percentages
+- **Dual Backend**: Memory adapter (fast) with Redis fallback (persistent)
+- **Rails Integration**: Seamless integration with Rails, including request store caching
+- **DSL Support**: Define features in a Ruby DSL file (`config/features.rb`)
+- **Thread-Safe**: All operations are thread-safe for concurrent access
+- **Performance**: Optimized for speed with memory-first caching strategy
+- **Advanced Features**: Circuit breaker, audit logging, performance metrics, versioning, and more
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'magick'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install magick
+```
+
+## Installation
+
+After adding the gem to your Gemfile and running `bundle install`, generate the configuration file:
+
+```bash
+rails generate magick:install
+```
+
+This will create `config/initializers/magick.rb` with a basic configuration.
+
+## Configuration
+
+### Basic Configuration
+
+The generator creates `config/initializers/magick.rb` with sensible defaults. You can also create it manually:
+
+```ruby
+Magick.configure do
+  # Configure Redis (optional)
+  redis url: ENV['REDIS_URL']
+
+  # Enable features
+  performance_metrics enabled: true
+  audit_log enabled: true
+  versioning enabled: true
+  warn_on_deprecated enabled: true
+end
+```
+
+### Advanced Configuration
+
+```ruby
+Magick.configure do
+  # Environment
+  environment Rails.env
+
+  # Memory TTL
+  memory_ttl 7200 # 2 hours
+
+  # Redis configuration
+  redis url: ENV['REDIS_URL'], namespace: 'magick:features'
+
+  # Circuit breaker settings
+  circuit_breaker threshold: 5, timeout: 60
+
+  # Async updates
+  async_updates enabled: true
+
+  # Enable services
+  performance_metrics enabled: true
+  audit_log enabled: true
+  versioning enabled: true
+  warn_on_deprecated enabled: true
+end
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+# Check if a feature is enabled
+if Magick.enabled?(:new_dashboard)
+  # Show new dashboard
+end
+
+# With context (user, role, etc.)
+if Magick.enabled?(:premium_features, user_id: current_user.id, role: current_user.role)
+  # Show premium features
+end
+```
+
+### Registering Features
+
+```ruby
+# Register a boolean feature
+Magick.register_feature(:new_dashboard,
+  type: :boolean,
+  default_value: false,
+  description: "New dashboard UI"
+)
+
+# Register a string feature
+Magick.register_feature(:api_version,
+  type: :string,
+  default_value: "v1",
+  description: "API version to use"
+)
+
+# Register a number feature
+Magick.register_feature(:max_results,
+  type: :number,
+  default_value: 10,
+  description: "Maximum number of results"
+)
+```
+
+### Feature Targeting
+
+```ruby
+feature = Magick[:new_dashboard]
+
+# Enable globally (for everyone, no targeting)
+feature.enable
+
+# Disable globally (for everyone, no targeting)
+feature.disable
+
+# Enable for specific user
+feature.enable_for_user(123)
+
+# Enable for specific group
+feature.enable_for_group("beta_testers")
+
+# Enable for specific role
+feature.enable_for_role("admin")
+
+# Enable for percentage of users (consistent)
+feature.enable_percentage_of_users(25) # 25% of users
+
+# Enable for percentage of requests (random)
+feature.enable_percentage_of_requests(50) # 50% of requests
+
+# Enable for date range
+feature.enable_for_date_range('2024-01-01', '2024-12-31')
+
+# Enable for IP addresses
+feature.enable_for_ip_addresses('192.168.1.0/24', '10.0.0.1')
+
+# Enable for custom attributes
+feature.enable_for_custom_attribute(:subscription_tier, ['premium', 'enterprise'])
+```
+
+### DSL Configuration
+
+Create `config/features.rb`:
+
+```ruby
+# Boolean features
+boolean_feature :new_dashboard, default: false, description: "New dashboard UI"
+boolean_feature :dark_mode, default: false, description: "Dark mode theme"
+
+# String features
+string_feature :api_version, default: "v1", description: "API version"
+
+# Number features
+number_feature :max_results, default: 10, description: "Maximum results per page"
+
+# With status
+feature :experimental_feature,
+  type: :boolean,
+  default_value: false,
+  status: :deprecated,
+  description: "Experimental feature (deprecated)"
+
+# With dependencies (feature will only be enabled if dependencies are enabled)
+boolean_feature :advanced_feature,
+  default: false,
+  description: "Advanced feature requiring base_feature",
+  dependencies: [:base_feature]
+
+# Multiple dependencies
+boolean_feature :premium_feature,
+  default: false,
+  description: "Premium feature requiring multiple features",
+  dependencies: [:base_feature, :auth_feature]
+
+# Add dependencies after feature definition
+add_dependency(:another_feature, :required_feature)
+```
+
+### In Controllers
+
+```ruby
+class DashboardController < ApplicationController
+  def show
+    if Magick.enabled?(:new_dashboard, user_id: current_user.id, role: current_user.role)
+      render :new_dashboard
+    else
+      render :old_dashboard
+    end
+  end
+end
+```
+
+### Advanced Features
+
+#### Feature Variants (A/B Testing)
+
+```ruby
+feature = Magick[:button_color]
+feature.set_variants([
+  { name: 'blue', value: '#0066cc', weight: 50 },
+  { name: 'green', value: '#00cc66', weight: 30 },
+  { name: 'red', value: '#cc0000', weight: 20 }
+])
+
+variant = feature.get_variant
+# Returns 'blue', 'green', or 'red' based on weights
+```
+
+#### Feature Dependencies
+
+```ruby
+feature = Magick[:advanced_feature]
+feature.add_dependency(:base_feature)
+# advanced_feature will only be enabled if base_feature is also enabled
+```
+
+#### Export/Import
+
+```ruby
+# Export features
+json_data = Magick.export(format: :json)
+File.write('features.json', json_data)
+
+# Import features
+Magick.import(File.read('features.json'))
+```
+
+#### Versioning and Rollback
+
+```ruby
+# Save current state as version
+Magick.versioning.save_version(:my_feature, created_by: current_user.id)
+
+# Rollback to previous version
+Magick.versioning.rollback(:my_feature, version: 2)
+```
+
+#### Performance Metrics
+
+```ruby
+# Get average duration for feature checks
+avg_duration = Magick.performance_metrics.average_duration(feature_name: :my_feature)
+
+# Get most used features
+most_used = Magick.performance_metrics.most_used_features(limit: 10)
+
+# Get usage count
+count = Magick.performance_metrics.usage_count(:my_feature)
+```
+
+#### Audit Logging
+
+```ruby
+# View audit log entries
+entries = Magick.audit_log.entries(feature_name: :my_feature, limit: 100)
+entries.each do |entry|
+  puts "#{entry.timestamp}: #{entry.action} by #{entry.user_id}"
+end
+```
+
+## Architecture
+
+### Adapters
+
+Magick uses a dual-adapter strategy:
+
+1. **Memory Adapter**: Fast, in-memory storage with TTL support
+2. **Redis Adapter**: Persistent storage for distributed systems (optional)
+
+The registry automatically falls back from memory to Redis if a feature isn't found in memory. When features are updated, both adapters are updated simultaneously.
+
+#### Memory-Only Mode
+
+If Redis is not configured, Magick works in **memory-only mode**:
+- ✅ Fast, zero external dependencies
+- ✅ Perfect for single-process applications or development
+- ⚠️ **No cross-process cache invalidation** - each process has isolated cache
+- ⚠️ Changes in one process won't be reflected in other processes
+
+#### Redis Mode (Recommended for Production)
+
+With Redis configured:
+- ✅ Cross-process cache invalidation via Redis Pub/Sub
+- ✅ Persistent storage across restarts
+- ✅ Zero Redis calls on feature checks (only memory lookups)
+- ✅ Automatic cache invalidation when features change in any process
+
+### Feature Types
+
+- `:boolean` - True/false flags
+- `:string` - String values
+- `:number` - Numeric values
+
+### Feature Status
+
+- `:active` - Feature is active and can be enabled
+- `:inactive` - Feature is disabled for everyone
+- `:deprecated` - Feature is deprecated (can be enabled with `allow_deprecated: true` in context)
+
+## Testing
+
+Use the testing helpers in your RSpec tests:
+
+```ruby
+RSpec.describe MyFeature do
+  it 'works with feature enabled' do
+    with_feature_enabled(:new_feature) do
+      # Test code here
+    end
+  end
+
+  it 'works with feature disabled' do
+    with_feature_disabled(:new_feature) do
+      # Test code here
+    end
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Magick
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a Magick configuration file at config/initializers/magick.rb'
+
+      def create_initializer
+        template 'magick.rb', 'config/initializers/magick.rb'
+      end
+
+      def show_readme
+        readme 'README' if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/magick/install/templates/README

@@ -0,0 +1,25 @@
+== Magick Install Generator
+
+The generated configuration includes:
+- Performance metrics tracking
+- Audit logging
+- Versioning support
+- Deprecation warnings
+
+Optional features (commented out by default):
+- Redis adapter configuration
+- Memory TTL customization
+- Circuit breaker settings
+- Async updates
+
+You can customize the configuration by editing the generated file.
+
+Usage:
+  rails generate magick:install
+
+For more information, see:
+- README.md
+- config/magick.rb.example
+
+This generator creates a basic Magick configuration file at:
+  config/initializers/magick.rb

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

@@ -0,0 +1,32 @@
+# Magick Configuration
+# Generated by: rails generate magick:install
+#
+# For more configuration options, see:
+# https://github.com/andrew-woblavobla/magick
+
+Magick.configure do
+  # Configure Redis (optional - gem works without it using memory-only adapter)
+  # Uncomment to use Redis:
+  # redis url: ENV['REDIS_URL'], namespace: 'magick:features'
+
+  # Configure memory adapter TTL (default: 3600 seconds = 1 hour)
+  # memory_ttl 7200 # 2 hours
+
+  # Configure circuit breaker for Redis failures
+  # circuit_breaker threshold: 5, timeout: 60
+
+  # Enable async updates for Redis (non-blocking, improves performance)
+  # async_updates enabled: true
+
+  # Enable performance metrics tracking
+  performance_metrics enabled: true
+
+  # Enable audit logging (tracks who changed what, when)
+  audit_log enabled: true
+
+  # Enable versioning support (allows rollback)
+  versioning enabled: true
+
+  # Enable deprecation warnings in logs
+  warn_on_deprecated enabled: true
+end

data/lib/magick/adapters/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Magick
+  module Adapters
+    class Base
+      def get(feature_name, key)
+        raise NotImplementedError, "#{self.class} must implement #get"
+      end
+
+      def set(feature_name, key, value)
+        raise NotImplementedError, "#{self.class} must implement #set"
+      end
+
+      def delete(feature_name)
+        raise NotImplementedError, "#{self.class} must implement #delete"
+      end
+
+      def exists?(feature_name)
+        raise NotImplementedError, "#{self.class} must implement #exists?"
+      end
+
+      def all_features
+        raise NotImplementedError, "#{self.class} must implement #all_features"
+      end
+    end
+  end
+end

data/lib/magick/adapters/memory.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'thread'
+
+module Magick
+  module Adapters
+    class Memory < Base
+      def initialize
+        @store = {}
+        @mutex = Mutex.new
+        @ttl = {}
+        @default_ttl = 3600 # 1 hour default TTL
+      end
+
+      def get(feature_name, key)
+        mutex.synchronize do
+          cleanup_expired
+          feature_data = store[feature_name.to_s]
+          return nil unless feature_data
+
+          value = feature_data[key.to_s]
+          deserialize_value(value)
+        end
+      end
+
+      def set(feature_name, key, value)
+        mutex.synchronize do
+          feature_name_str = feature_name.to_s
+          store[feature_name_str] ||= {}
+          store[feature_name_str][key.to_s] = serialize_value(value)
+          update_ttl(feature_name_str)
+        end
+      end
+
+      def delete(feature_name)
+        mutex.synchronize do
+          feature_name_str = feature_name.to_s
+          store.delete(feature_name_str)
+          ttl.delete(feature_name_str)
+        end
+      end
+
+      def exists?(feature_name)
+        mutex.synchronize do
+          cleanup_expired
+          store.key?(feature_name.to_s)
+        end
+      end
+
+      def all_features
+        mutex.synchronize do
+          cleanup_expired
+          store.keys
+        end
+      end
+
+      def clear
+        mutex.synchronize do
+          @store = {}
+          @ttl = {}
+        end
+      end
+
+      def set_ttl(feature_name, seconds)
+        mutex.synchronize do
+          ttl[feature_name.to_s] = Time.now.to_i + seconds
+        end
+      end
+
+      private
+
+      attr_reader :store, :mutex, :ttl, :default_ttl
+
+      def cleanup_expired
+        now = Time.now.to_i
+        expired_keys = ttl.select { |_key, expiry| expiry < now }.keys
+        expired_keys.each do |key|
+          store.delete(key)
+          ttl.delete(key)
+        end
+      end
+
+      def update_ttl(feature_name)
+        ttl[feature_name] = Time.now.to_i + default_ttl
+      end
+
+      def serialize_value(value)
+        case value
+        when Hash, Array
+          Marshal.dump(value)
+        else
+          value
+        end
+      end
+
+      def deserialize_value(value)
+        return nil if value.nil?
+
+        case value
+        when String
+          # Try to unmarshal if it's a serialized hash/array
+          begin
+            Marshal.load(value)
+          rescue StandardError
+            value
+          end
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/magick/adapters/redis.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Magick
+  module Adapters
+    class Redis < Base
+      def initialize(redis_client = nil)
+        @redis = redis_client || default_redis_client
+        @namespace = 'magick:features'
+        raise AdapterError, 'Redis client is required' unless @redis
+      rescue StandardError => e
+        raise AdapterError, "Failed to initialize Redis adapter: #{e.message}"
+      end
+
+      def get(feature_name, key)
+        value = redis.hget(key_for(feature_name), key.to_s)
+        deserialize_value(value)
+      rescue StandardError => e
+        raise AdapterError, "Failed to get from Redis: #{e.message}"
+      end
+
+      def set(feature_name, key, value)
+        redis.hset(key_for(feature_name), key.to_s, serialize_value(value))
+      rescue StandardError => e
+        raise AdapterError, "Failed to set in Redis: #{e.message}"
+      end
+
+      def delete(feature_name)
+        redis.del(key_for(feature_name))
+      rescue StandardError => e
+        raise AdapterError, "Failed to delete from Redis: #{e.message}"
+      end
+
+      def exists?(feature_name)
+        redis.exists?(key_for(feature_name))
+      rescue StandardError => e
+        raise AdapterError, "Failed to check existence in Redis: #{e.message}"
+      end
+
+      def all_features
+        pattern = "#{namespace}:*"
+        keys = redis.keys(pattern)
+        keys.map { |key| key.sub("#{namespace}:", '') }
+      rescue StandardError => e
+        raise AdapterError, "Failed to get all features from Redis: #{e.message}"
+      end
+
+      private
+
+      attr_reader :redis, :namespace
+
+      def key_for(feature_name)
+        "#{namespace}:#{feature_name}"
+      end
+
+      def default_redis_client
+        return nil unless defined?(Redis)
+
+        require 'redis'
+        ::Redis.new
+      rescue StandardError
+        nil
+      end
+
+      def serialize_value(value)
+        case value
+        when Hash, Array
+          Marshal.dump(value)
+        when true
+          'true'
+        when false
+          'false'
+        else
+          value.to_s
+        end
+      end
+
+      def deserialize_value(value)
+        return nil if value.nil?
+
+        # Try to unmarshal if it's a serialized hash/array
+        if value.is_a?(String) && value.start_with?("\x04\x08")
+          begin
+            Marshal.load(value)
+          rescue StandardError
+            value
+          end
+        elsif value == 'true'
+          true
+        elsif value == 'false'
+          false
+        else
+          value
+        end
+      end
+    end
+  end
+end