rollout-redis 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d7d811416500c11c77ca8c8490d301c0ce266db5dc6e7967e07c25e435be454
+  data.tar.gz: c8e76ea2823845c3c3ef2d1929e4e1e75d0f19688ac99b5e4a6e903dae3a57ec
+SHA512:
+  metadata.gz: e03a813c99336b16cdee142457f04e56a3cb12b8292f95034a583cd79ae12e97b9586db54cb3070d297bf762259acdb3a9026496124a1a6a40dbcf880fd4433d
+  data.tar.gz: 632ad6cf617ba379149383ad21e1033d5c6c3c12f9f8de58b1c1465d1440e957760f7ac4c15c011886dd9b188c73f2387b16d7cc144f4ece16446183f8dfcc21

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+All changes to `rollout-redis` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [0.1.0] - 2023-10-23
+
+- Initial version

data/README.md

@@ -0,0 +1,193 @@
+# rollout-redis 🚀
+
+[![Gem Version](https://badge.fury.io/rb/rollout-redis.svg)](https://badge.fury.io/rb/rollout-redis)
+
+Fast and easy feature flags based on Redis. 
+
+Based on the discontinued [rollout](https://github.com/fetlife/rollout) project, removing some capabilities, including some new features and supporting latest Redis versions.
+
+Topics covered in this README:
+
+- [Install it](#install-it)
+- [Quick Start](#quick-start-💨)
+- [Advanced features](#advanced-features-🦾)
+  - [Gradual activation based on percentages](#gradual-activation-based-on-percentages)
+  - [Caching Feature Flags](#caching-feature-flags)
+  - [Auto-deactivating flags](#auto-deactivating-flags)
+- [Migrating from rollout gem](#migrating-from-rollout-gem-🚨)
+- [Changelog](#changelog)
+- [Contributing](#contributing)
+
+## Install it 
+
+```bash
+gem install rollout-redis
+```
+
+## Quick Start 💨
+
+Instantiate the `Rollout` class sending a `Redis` instance as a parameter.
+
+```ruby
+require 'redis'
+require 'rollout'
+
+@redis ||= Redis.new(
+        host: ENV.fetch('REDIS_HOST'),
+        port: ENV.fetch('REDIS_PORT')
+      )
+@rollout ||= Rollout.new(@redis)
+```
+
+Now you can activate Feature Flags:
+
+```ruby
+@rollout.activate('FEATURE_FLAG_NAME') # => true/false
+```
+
+Verify if a feature is currently enabled:
+
+```ruby
+if @rollout.active?('FEATURE_FLAG_NAME')
+  # your new code here...
+end
+```
+
+An alternative to the if check, is to wrap your code under the `with_feature` method. The wrapped code will be performed only if the feature flag is active:
+
+```ruby
+@rollout.with_feature('FEATURE_FLAG_NAME') do
+  # your new code here...
+end
+```
+
+If there is an issue, you have the option to disable a feature:
+
+```ruby
+@rollout.deactivate('FEATURE_FLAG_NAME')
+```
+
+## Advanced features 🦾
+
+### Gradual activation based on percentages
+
+When introducing a new feature, it's a recommended practice to gradually enable it for a specific portion of your target audience to evaluate its impact. To achieve this, you can utilize the `activate` method, as shown below:
+
+```ruby
+@rollout.activate('FEATURE_FLAG_NAME', 20)
+```
+
+Now, to know if a feature flags is enabled, you need to provide a determinator (in this example, we're using the user email):
+
+```ruby
+if @rollout.active?('FEATURE_FLAG_NAME', user_email)
+  # your new code here...
+end
+```
+
+The gradual activation also works wrapping your code within the `with_feature` method, you just need to provde the determinator you want to use.
+
+```ruby
+@rollout.with_feature('FEATURE_FLAG_NAME', user_email) do
+  # your new code here...
+end
+```
+
+It's important to note that if you use the `active?` method without specifying a determinator to determine whether this subset of the audience should see the new feature, it will always return `false` since the activation percentage is less than 100%. See:
+
+```ruby
+@rollout.activate('FEATURE_FLAG_NAME', 20)
+@rollout.active?('FEATURE_FLAG_NAME') # => false
+```
+
+### Caching Feature Flags
+
+The Rollout gem is tightly integrated with Redis for feature flag status management. Consequently, occasional connectivity issues between your application and the Redis storage may arise.
+
+To prevent potential application degradation when the Redis storage is unavailable, you can enable feature flag status caching during the gem's instantiation:
+
+```ruby
+@rollout ||= Rollout.new(redis).with_cache
+```
+
+Additionally, you can specify extra parameters to configure the duration (in seconds) for which the feature flag status is stored in the cache. By default, this duration is set to 300 seconds (5 minutes):
+
+```ruby
+@rollout ||= Rollout.new(redis)
+              .with_cache(expires_in: 300)
+```
+
+In the case that you need to clear the cache at any point, you can make use of the `clean_cache` method:
+
+```ruby
+@rollout.clean_cache
+```
+
+### Auto-deactivating flags
+
+If you want to allow the gem to deactivate your feature flag automatically when a threshold of erros is reached, you can enable the degrade feature using the `with_degrade` method.
+
+```ruby
+@rollout ||= Rollout.new(redis)
+              .with_cache
+              .with_degrade(sample: 5000, min: 100, threshold: 0.1)
+```
+
+So now, instead of using the `active?` method, you need to wrap your new code under the `with_feature` method.
+
+```ruby
+@rollout.with_feature('FEATURE_FLAG_NAME') do
+  # your new feature code here...
+end
+```
+
+When any unexpected error appears during the wrapped code execution, the Rollout gem will take it into account for automatically deactivating the feature flag if the threshold of errors is reached. All the managed or captured errors inside the wrapped code will not be taken into consideration.
+
+## Migrating from rollout gem 🚨
+
+If you are currently using the unmaintained [rollout](https://github.com/fetlife/rollout) gem, you should consider checking this [migration guide](https://github.com/jcagarcia/rollout-redis/blob/main/MIGRATING_FROM_ROLLOUT_GEM.md) for start using the new `rollout-redis` gem.
+
+## Changelog
+
+If you're interested in seeing the changes and bug fixes between each version of `rollout-redis`, read the [Changelog](https://github.com/jcagarcia/rollout-redis/blob/main/CHANGELOG.md).
+
+## Contributing
+
+We welcome and appreciate contributions from the open-source community. Before you get started, please take a moment to review the guidelines below.
+
+### How to Contribute
+
+1. Fork the repository.
+2. Clone the repository to your local machine.
+3. Create a new branch for your contribution.
+4. Make your changes and ensure they meet project standards.
+5. Commit your changes with clear messages.
+6. Push your branch to your GitHub repository.
+7. Open a pull request in our repository.
+8. Participate in code review and address feedback.
+9. Once approved, your changes will be merged.
+
+### Development
+
+This project is dockerized. Once you clone the repository, you can use the `Make` commands to build the project.
+
+```shell
+make build
+```
+
+You can pass the tests running:
+
+```shell
+make test
+```
+
+### Issue Tracker
+
+Open issues on the GitHub issue tracker with clear information.
+
+### Contributors
+
+*   Juan Carlos García - Creator - https://github.com/jcagarcia
+
+The `rollout-redis` gem is based on the discontinued [rollout](https://github.com/fetlife/rollout) project, created by [James Golick](https://github.com/jamesgolick)
+

data/Rakefile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/rollout/feature.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+class Rollout
+    class Feature
+      attr_accessor :percentage
+      attr_reader :name, :data
+
+      RAND_BASE = (2**32 - 1) / 100.0
+  
+      def initialize(name, data={})
+        @name = name
+        @data = data
+        @percentage = @data[:percentage]
+      end
+  
+      def active?(determinator=nil)
+        if determinator
+          determinator_in_percentage?(determinator)
+        else
+          @percentage == 100
+        end
+      end
+
+      def add_request
+        if @data[:requests]
+          @data[:requests] = @data[:requests] + 1
+        else
+          @data[:requests] = 1
+        end
+      end
+
+      def add_error
+        if @data[:errors]
+          @data[:errors] = @data[:errors] + 1
+        else
+          @data[:errors] = 1
+        end
+      end
+
+      def requests
+        @data[:requests] || 0
+      end
+
+      def errors
+        @data[:errors] || 0
+      end
+  
+      private
+  
+      def determinator_in_percentage?(determinator)
+        Zlib.crc32(determinator) < RAND_BASE * @percentage
+      end
+    end
+  end

data/lib/rollout/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Rollout
+  VERSION = '0.1.0'
+end

data/lib/rollout.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'rollout/feature'
+require 'rollout/version'
+require 'redis'
+require 'json'
+
+class Rollout
+
+  class Error < StandardError; end
+
+  attr_reader :storage
+
+  def initialize(storage)
+    @storage = storage
+    @cache_enabled = false
+    @degrade_enabled = false
+  end
+
+  def with_cache(expires_in: 300)
+    @cache_enabled = true
+    @cache_time = expires_in
+    @cache = {}
+
+    self
+  end
+
+  def with_degrade(min: 100, threshold: 0.1)
+    @degrade_enabled = true
+    @degrade_min = min
+    @degrade_threshold = threshold
+
+    self
+  end
+
+  def activate(feature_name, percentage=100)
+    data = { percentage: percentage }
+    feature = Feature.new(feature_name, data)
+    @cache[feature_name] = {
+      feature: feature,
+      timestamp: Time.now.to_i
+    } if @cache_enabled
+    save(feature) == "OK"
+  end
+
+  def activate_percentage(feature_name, percentage)
+    activate(feature_name, percentage)
+  end
+
+  def deactivate(feature_name)
+    del(feature_name)
+  end
+
+  def active?(feature_name, determinator = nil)
+    feature = get(feature_name, determinator)
+    return false unless feature
+
+    active = feature.active?(determinator)
+
+    if active && @degrade_enabled
+      feature.add_request
+      save(feature)
+    end
+
+    active
+  end
+
+  def with_feature_flag(feature_name, determinator = nil, &block)
+    yield if active?(feature_name, determinator)
+  rescue => e
+    feature = get(feature_name, determinator)
+    if @degrade_enabled && feature
+      feature.add_error
+      save(feature)
+
+      deactivate(feature_name) if degraded?(feature)
+    end
+    raise e
+  end
+
+  def clean_cache
+    return unless @cache_enabled
+
+    @cache = {}
+  end
+
+  def migrate_from_rollout_format
+    keys = @storage.keys('feature:*')
+
+    keys.each do |old_key|
+      new_key = old_key.gsub('feature:', 'feature-rollout-redis:')
+      old_data = @storage.get(old_key)
+
+      if old_data
+        percentage = old_data.split('|')[0].to_i
+
+        new_data = {
+          percentage: percentage,
+          requests: 0,
+          errors: 0
+        }.to_json
+
+        @storage.set(new_key, new_data)
+
+        puts "Migrated key: #{old_key} to #{new_key} with data #{new_data}"
+      end
+    end
+  end
+
+  private
+
+  def get(feature_name, determinator = nil)
+    feature = from_redis(feature_name)
+    return unless feature
+
+    @cache[feature_name] = {
+      feature: feature,
+      timestamp: Time.now.to_i
+    } if @cache_enabled
+
+    feature
+  rescue ::Redis::BaseError => e
+    cached_feature = from_cache(feature_name)
+    raise Rollout::Error.new(e) unless cached_feature
+
+    cached_feature
+  end
+
+  def save(feature)
+    @storage.set(key(feature.name), feature.data.to_json)
+  end
+  
+  def del(feature_name)
+    @storage.del(key(feature_name)) == 1
+  end
+
+  def from_cache(feature_name)
+    return nil unless @cache_enabled
+
+    cached = @cache[feature_name]
+
+    if expired?(cached[:timestamp])
+      @cache.delete(feature_name)
+      return nil
+    end
+
+    cached[:feature]
+  end
+
+  def from_redis(feature_name)
+    data = @storage.get(key(feature_name))
+    return unless data
+    Feature.new(feature_name, JSON.parse(data, symbolize_names: true))
+  end
+
+  def expired?(timestamp)
+    Time.now.to_i - timestamp > @cache_time
+  end
+
+  def degraded?(feature)
+    return false if !@degrade_enabled
+    return false if feature.requests < @degrade_min
+
+    feature.errors > @degrade_threshold * feature.requests
+  end
+
+  def key(name)
+    "feature-rollout-redis:#{name}"
+  end
+end

data/rollout-redis.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require 'rollout/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'rollout-redis'
+  spec.version     = Rollout::VERSION
+  spec.authors     = ['Juan Carlos García']
+  spec.email       = ['jugade92@gmail.com']
+  spec.description = 'Fast and easy feature flags based on the latest Redis versions.'
+  spec.summary     = 'Fast and easy feature flags based on the latest Redis versions.'
+  spec.homepage    = 'https://github.com/jcagarcia/rollout-redis'
+  spec.license     = 'MIT'
+
+  files = Dir["lib/**/*.rb", "lib/**/tasks/*.rake"]
+  rootfiles = ["CHANGELOG.md", "rollout-redis.gemspec", "Rakefile", "README.md"]
+
+  spec.files = rootfiles + files
+  spec.executables = []
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = '>= 2.3'
+
+  spec.add_runtime_dependency 'redis', '>= 4.0', '<= 5'
+
+  spec.add_development_dependency 'bundler', '>= 2.4'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'mock_redis', '~> 0.37'
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: rollout-redis
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Juan Carlos García
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-10-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<="
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<="
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: mock_redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.37'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.37'
+description: Fast and easy feature flags based on the latest Redis versions.
+email:
+- jugade92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- lib/rollout.rb
+- lib/rollout/feature.rb
+- lib/rollout/version.rb
+- rollout-redis.gemspec
+homepage: https://github.com/jcagarcia/rollout-redis
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Fast and easy feature flags based on the latest Redis versions.
+test_files: []