feature_guard 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - "2.0.0"
+script: bundle exec rspec

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in feature_guard.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 t ddddddd
+
+MIT License
+
+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,83 @@
+[![Build Status](https://api.travis-ci.org/tdumitrescu/feature_guard.png)](https://travis-ci.org/tdumitrescu/feature_guard)
+
+# FeatureGuard
+
+Lightweight Redis-based feature-flagging for Ruby apps. Provides a simple syntax for enabling and disabling features, or gradually ramping up and down by enabling features for a percentage of total traffic.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'feature_guard'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install feature_guard
+
+## Usage
+
+Check whether a feature is enabled globally:
+
+```ruby
+FeatureGuard.enabled? :my_feature
+```
+
+Globally enable or disable a feature:
+
+```ruby
+FeatureGuard.enable  :my_feature
+FeatureGuard.disable :my_feature
+FeatureGuard.toggle  :my_feature
+```
+
+Feature names can be strings or symbols. No data setup is necessary; any check for a feature which has never been enabled simply returns false.
+
+For more fine-grained control, set a ramp-up value to decide which percentage of traffic should see the feature:
+
+```ruby
+FeatureGuard.set_ramp  :my_feature, 30.5  # 30.5%
+FeatureGuard.bump_ramp :my_feature, 12    # 30.5 + 12 = 42.5%
+FeatureGuard.bump_ramp :my_feature        # 42.5 + 10 = 52.5%
+
+FeatureGuard.ramp_val :my_feature # 52.5
+```
+
+`.set_ramp` sets the ramp-up value; `.bump_ramp` increments or decrements it by a given value (defaults to 10.0). Check the current ramp-up value with `.ramp_val`.
+
+Check whether to show the feature at the current ramp-up value:
+
+```ruby
+FeatureGuard.allow? :my_feature, user_id
+# true for 52.5% of user_id values
+
+FeatureGuard.allow? :my_feature
+# true for 52.5% of checks (random)
+```
+
+The optional second argument to`.allow?` can be of any type (e.g., user ID or name or even an object). It is hashed with the feature name to create a reproducible numeric value for checking whether to return true or false based on the current ramp-up value. With no second argument, `.allow?` uses a new random value on every call.
+
+## Configuration
+
+Optionally change the Redis client with:
+
+```ruby
+FeatureGuard.redis = my_redis_client
+```
+
+Setting `FeatureGuard.redis` to `nil` will revert it to a new default instance (`Redis.new`).
+
+## Running tests
+
+    $ bundle exec rspec
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/feature_guard.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/feature_guard/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Ted Dumitrescu"]
+  gem.email         = ["miscmisc@cmme.org"]
+  gem.summary       = %q{Simple Redis-based feature-flagging}
+  gem.description   = <<end
+Turn code on or off with Redis controls, allowing simple enabled/disabled states 
+as well as finer-grained percentage-based control.
+end
+  gem.homepage      = "https://github.com/tdumitrescu/feature_guard"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "feature_guard"
+  gem.require_paths = ["lib"]
+  gem.version       = FeatureGuard::VERSION
+
+  gem.add_dependency "redis", "~> 3.0"
+
+  gem.add_development_dependency "fakeredis", "~> 0.4"
+  gem.add_development_dependency "rspec",     "~> 2.13"
+end

data/lib/feature_guard.rb

@@ -0,0 +1,20 @@
+require "redis" unless defined? Redis
+
+require "feature_guard/version"
+require "feature_guard/guard"
+
+module FeatureGuard
+  class << self
+    attr_writer :redis
+
+    def redis
+      @redis ||= Redis.new
+    end
+
+    [:allow?, :bump_ramp, :disable, :enable, :toggle, :enabled?, :ramp_val, :set_ramp].each do |mname|
+      define_method(mname) do |key, *args|
+        Guard.new(key).send(mname, *args)
+      end
+    end
+  end
+end

data/lib/feature_guard/guard.rb

@@ -0,0 +1,75 @@
+module FeatureGuard; class Guard
+  attr_reader :feature_name
+
+  def initialize(_feature_name)
+    @feature_name = _feature_name
+  end
+
+  # binary flag methods (enabled/disabled)
+  def disable
+    redis.set(flag_key, 0)
+  end
+
+  def enable
+    redis.set(flag_key, 1)
+  end
+
+  def enabled?
+    redis.get(flag_key).tap { |v| return (!v.nil? && v.to_i > 0) }
+  rescue
+    false
+  end
+
+  def toggle
+    enabled? ? disable : enable
+  end
+
+  # ramp methods (0.0 .. 100.0)
+  def allow?(val = nil)
+    val = val.nil? ? random_val : hashed_val(val)
+    val < ramp_val
+  end
+
+  def bump_ramp(amount = 10.0)
+    set_ramp(ramp_val + amount)
+  end
+
+  def ramp_val
+    redis.get(ramp_key).to_f
+  end
+
+  def set_ramp(new_val)
+    new_val = new_val.to_f
+    new_val = 100.0 if new_val > 100.0
+    new_val = 0.0   if new_val < 0.0
+
+    redis.set(ramp_key, new_val)
+    new_val
+  end
+
+  private
+
+  def feature_key
+    @feature_key ||= feature_name.to_s.split.join('_')
+  end
+
+  def flag_key
+    @flag_key ||= "fgf_#{feature_key}"
+  end
+
+  def ramp_key
+    @ramp_key ||= "fgr_#{feature_key}"
+  end
+
+  def hashed_val(s)
+    (Digest::MD5.hexdigest("#{ramp_key}_#{s}").to_i(16) % 10000).to_f / 100.0
+  end
+
+  def random_val
+    rand * 100.0
+  end
+
+  def redis
+    FeatureGuard.redis
+  end
+end; end

data/lib/feature_guard/version.rb

@@ -0,0 +1,3 @@
+module FeatureGuard
+  VERSION = "0.1.0"
+end

data/spec/feature_guard/guard_spec.rb

@@ -0,0 +1,83 @@
+require "spec_helper"
+
+describe FeatureGuard::Guard do
+  let(:feature) { 'exciting new code' }
+  let(:guard)   { FeatureGuard::Guard.new(feature) }
+
+  describe '#allow?' do
+    before { guard.set_ramp 30.0 }
+
+    context 'when no value is provided' do
+      subject { guard.allow? }
+
+      it 'uses a random value' do
+        expect(guard).to receive(:random_val).and_return(29.9)
+        expect(subject).to be_true
+      end
+    end
+
+    context 'when a value is provided' do
+      subject { guard.allow? 'username_or_id' }
+
+      it 'hashes the value together with the feature name' do
+        expect(guard).to receive(:hashed_val).and_return(30.1)
+        expect(subject).to be_false
+      end
+    end
+  end
+
+  describe '#bump_ramp' do
+    before { guard.set_ramp(5.0) }
+
+    it 'changes the ramp value by the given amount' do
+      expect { guard.bump_ramp 14.5 }.to change { guard.ramp_val }.from(5.0).to(19.5)
+    end
+
+    it 'defaults to bumping by 10.0' do
+      expect { guard.bump_ramp }.to change { guard.ramp_val }.from(5.0).to(15.0)
+    end
+  end
+
+  describe '#enabled?' do
+    subject { guard.enabled? }
+
+    context 'for a non-existent flag' do
+      it { should be_false }
+    end
+
+    context 'for an enabled flag' do
+      before { guard.enable }
+
+      it { should be_true }
+    end
+  end
+
+  describe '#set_ramp' do
+    let(:new_val) { 51.7 }
+
+    subject { guard.set_ramp new_val }
+
+    it 'sets the ramp value' do
+      expect { subject }.to change { guard.ramp_val }.to new_val
+    end
+
+    it 'returns the new ramp value' do
+      expect(subject).to eq new_val
+    end
+
+    it 'does not set the value above 100.0' do
+      expect(guard.set_ramp 190.0).to eq 100.0
+    end
+
+    it 'does not set the value below 0.0' do
+      expect(guard.set_ramp -190.0).to eq 0.0
+    end
+  end
+
+  describe '#toggle' do
+    it 'toggles the feature on or off' do
+      expect { guard.toggle }.to change { guard.enabled? }.from(false).to(true)
+      expect { guard.toggle }.to change { guard.enabled? }.from(true).to(false)
+    end
+  end
+end

data/spec/feature_guard_spec.rb

@@ -0,0 +1,53 @@
+require "spec_helper"
+
+describe FeatureGuard do
+  let(:feature) { :some_feature_name }
+
+  describe 'enabling and disabling a feature' do
+    it 'turns the feature on and off in succession' do
+      expect {
+        FeatureGuard.enable feature
+      }.to change {
+        FeatureGuard.enabled? feature
+      }.from(false).to(true)
+
+      expect {
+        FeatureGuard.disable feature
+      }.to change {
+        FeatureGuard.enabled? feature
+      }.from(true).to(false)
+    end
+  end
+
+  describe 'ramping a feature up and down' do
+    let(:user_id) { 5435 }
+
+    it 'allows a percentage of calls to use the feature' do
+      expect {
+        FeatureGuard.set_ramp feature, 100.0
+      }.to change {
+        FeatureGuard.allow? feature, user_id
+      }.from(false).to(true)
+
+      expect {
+        FeatureGuard.set_ramp feature, 0.0
+      }.to change {
+        FeatureGuard.allow? feature, user_id
+      }.from(true).to(false)
+    end
+  end
+
+  describe '.enabled?' do
+    subject { FeatureGuard.enabled? feature }
+
+    context 'for a non-existent flag' do
+      it { should be_false }
+    end
+
+    context 'when the Redis client blows up or is non-existent' do
+      before { FeatureGuard.stub(redis: nil) }
+
+      it { should be_false }
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+require "fakeredis/rspec"
+require "feature_guard"
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  config.order = 'random'
+
+  config.expect_with(:rspec) do |c|
+    c.syntax = :expect
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: feature_guard
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Ted Dumitrescu
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: &2164594960 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2164594960
+- !ruby/object:Gem::Dependency
+  name: fakeredis
+  requirement: &2164594440 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: *2164594440
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2164593760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.13'
+  type: :development
+  prerelease: false
+  version_requirements: *2164593760
+description: ! "Turn code on or off with Redis controls, allowing simple enabled/disabled
+  states \nas well as finer-grained percentage-based control.\n"
+email:
+- miscmisc@cmme.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- feature_guard.gemspec
+- lib/feature_guard.rb
+- lib/feature_guard/guard.rb
+- lib/feature_guard/version.rb
+- spec/feature_guard/guard_spec.rb
+- spec/feature_guard_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/tdumitrescu/feature_guard
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Simple Redis-based feature-flagging
+test_files:
+- spec/feature_guard/guard_spec.rb
+- spec/feature_guard_spec.rb
+- spec/spec_helper.rb
+has_rdoc: