detour 0.0.1

data/.gitignore

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

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 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 detour.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jonathan Clem
+
+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,261 @@
+# Detour
+
+Rollouts for `ActiveRecord` models. It is a spiritual fork of [ArRollout](https://github.com/markpundsack/ar_rollout).
+
+| development status | master status | Code Climate |
+| ------------------ | ------------- | ------------ |
+| [![development status][dev_image]][branch_status] | [![master status][master_image]][branch_status] | [![Code Climate][code_climate_image]][code_climate]
+
+[dev_image]: https://api.travis-ci.org/jclem/detour.png?branch=development
+[master_image]: https://api.travis-ci.org/jclem/detour.png?branch=master
+[branch_status]: https://travis-ci.org/jclem/detour/branches
+[code_climate_image]: https://codeclimate.com/github/jclem/detour.png
+[code_climate]: https://codeclimate.com/github/jclem/detour
+
+## Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Marking a model as flaggable](#marking-a-model-as-flaggable)
+  - [Determining if a record is flagged into a feature](#determining-if-a-record-is-flagged-into-a-feature)
+  - [Feature operations](#feature-operations)
+    - [Creating features](#creating-features)
+    - [Destroying features](#destroying-features)
+    - [Flagging a record into a feature](#flagging-a-record-into-a-feature)
+    - [Removing a flag-in for a record for a feature](#removing-a-flag-in-for-a-record-for-a-feature)
+    - [Opt a record out of a feature](#opt-a-record-out-of-a-feature)
+    - [Un-opt out a record from a feature](#un-opt-out-a-record-from-a-feature)
+    - [Flag a programmatic group into a feature](#flag-a-programmatic-group-into-a-feature)
+    - [Remove a flag-in for a programmatic group for a feature](#remove-a-flag-in-for-a-programmatic-group-for-a-feature)
+    - [Flag a percentage of records into a feature](#flag-a-percentage-of-records-into-a-feature)
+    - [Remove a flag-in for a percentage of records for a feature](#remove-a-flag-in-for-a-percentage-of-records-for-a-feature)
+  - [Defining a default class](#defining-a-default-class)
+  - [Defining programmatic groups](#defining-programmatic-groups)
+- [Contributing](#contributing)
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'detour'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install detour
+
+## Usage
+
+`Detour` works by determining whether or not a specific record
+should have features accessible to it based on individual flags, flags for a
+percentage of records, or flags for a programmable group of records.
+
+### Marking a model as flaggable
+
+```ruby
+class User < ActiveRecord::Base
+  acts_as_flaggable
+end
+```
+
+Or, in order to user emails rather than IDs to identify records in rake tasks:
+
+```ruby
+class User < ActiveRecord::Base
+  acts_as_flaggable find_by: :email
+end
+```
+
+This module adds `has_many` associations to `User` for `flaggable_flags` (where
+the user has been individually flagged into a feature), `opt_out_flags` (where
+the user has been opted out of a feature), and `features` (the features that
+the user has been individually flagged into, regardless of opt outs).
+
+However, these methods aren't enough to determine whether or not the user is
+flagged into a specific feature. The `#has_feature?` method provided by
+`Detour::Flaggable` should be used for this.
+
+### Determining if a record is flagged into a feature
+
+`#has_feature?` has two methods of use. The first one, where it is passed a
+block, will increment a `failure_count` on the given feature if the block
+raises an exception (the exception is again raised after incrementing). This
+currently does not alter the behavior of the feature, but it services a metrics
+purpose:
+
+```ruby
+current_user.has_feature? :new_user_interface do
+  render_new_user_interface
+end
+```
+
+When not given a block, it simply returns a boolean, and does not watch for
+exceptions:
+
+```ruby
+if current_user.has_feature? :new_user_interface
+  render_new_user_interface
+end
+```
+
+Want to make use of both? `#has_feature?` returns a boolean even when passed
+a block:
+
+```ruby
+if current_user.has_feature? :new_user_interface do
+  render_new_user_interface
+end; else
+  render_old_user_interface
+end
+```
+
+### Feature operations
+
+Features and flags are intended to be controlled by a rake tasks. To create
+them programmatically, consult the documentation.
+
+#### Creating features
+
+```sh
+$ bundle exec rake detour:create[new_ui]
+```
+
+#### Destroying features
+
+```sh
+$ bundle exec rake detour:destroy[new_ui]
+```
+
+#### Flagging a record into a feature
+
+This task requires passing the feature name, the record's class, and the
+record's ID.
+
+```sh
+$ bundle exec rake detour:activate[new_ui,User,2]
+```
+
+#### Removing a flag-in for a record for a feature
+
+This task requires passing the feature name, the record's class, and the
+record's ID.
+
+```sh
+$ bundle exec rake detour:deactivate[new_ui,User,2]
+```
+
+#### Opt a record out of a feature
+
+This will ensure that `record.has_feature?(:feature)` will always be false for
+the given feature, regardless of other individual flag, percentage, or group
+rollouts that would otherwise target this record.
+
+This task requires passing the feature name, the record's class, and the
+record's ID.
+
+```sh
+$ bundle exec rake detour:opt_out[new_ui,User,2]
+```
+
+#### Un-opt out a record from a feature
+
+This task requires passing the feature name, the record's class, and the
+record's ID.
+
+```sh
+$ bundle exec rake detour:un_opt_out[new_ui,User,2]
+```
+
+#### Flag a programmatic group into a feature
+
+This task requires passing the feature name, the record class for the group,
+and the name of the group.
+
+```sh
+$ bundle exec rake detour:activate_group[new_ui,User,admins]
+```
+
+#### Remove a flag-in for a programmatic group for a feature
+
+This task requires passing the feature name, the record class for the group,
+and the name of the group.
+
+```sh
+$ bundle exec rake detour:deactivate_group[new_ui,User,admins]
+```
+
+#### Flag a percentage of records into a feature
+
+This relies on the following formula to determine if a record is flagged in to
+a feature based on percentage:
+
+```ruby
+record.id % 10 < percentage / 10
+```
+
+This task requires passing the feature name, the record class for the group,
+and the percentage of records to be flagged in.
+
+```sh
+$ bundle exec rake detour:activate_percentage[new_ui,User,20]
+```
+
+#### Remove a flag-in for a percentage of records for a feature
+
+This task requires passing the feature name, and the record class for the group.
+
+```sh
+$ bundle exec rake detour:deactivate_percentage[new_ui,User]
+```
+
+### Defining a default class
+
+In order to provide passing a class name into rake tasks, a default class can
+be set:
+
+```ruby
+Detour.configure do |config|
+  config.default_flaggable_class_name = "User"
+end
+```
+
+Then, in your rake tasks:
+
+```sh
+# Will activate feature "foo" for all instances of User that match the admins group.
+$ bundle exec rake detour:activate_group[foo,admins]
+```
+
+### Defining programmatic groups
+
+A specific group of records matching a given block can be flagged into a
+feature. In order to define these groups, use
+`Detour.configure`:
+
+```ruby
+Detour.configure do |config|
+  # Any User that returns truthy for `user.admin?` will be included in this
+  # group: `admins`.
+  config.define_user_group :admins do |user|
+    user.admin?
+  end
+
+  # Any FizzBuzz that returns truthy for `fizz_buzz.bar?` will be included in
+  # this group: `is_bar`.
+  config.define_fizz_buzz_group :is_bar do |fizz_buzz|
+    fizz_buzz.bar?
+  end
+end
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/detour/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/detour.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "detour/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "detour"
+  spec.version       = Detour::VERSION
+  spec.authors       = ["Jonathan Clem"]
+  spec.email         = ["jonathan@heroku.com"]
+  spec.summary       = %q{Rollouts (feature flags) for ActiveRecord models.}
+  spec.description   = %q{Rollouts (feature flags) for ActiveRecord models.}
+  spec.homepage      = "https://github.com/jclem/detour"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 1.9.3"
+
+  spec.add_dependency "activerecord", "~> 3.2"
+  spec.add_dependency "rails", "~> 3.2"
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec-rails"
+  spec.add_development_dependency "fakefs"
+  spec.add_development_dependency "shoulda-matchers"
+  spec.add_development_dependency "sqlite3-ruby"
+  spec.add_development_dependency "pry-debugger"
+  spec.add_development_dependency "yard"
+end

data/lib/detour/acts_as_flaggable.rb

@@ -0,0 +1,36 @@
+module Detour::ActsAsFlaggable
+  # Sets up ActiveRecord associations for the including class, and includes
+  # {Detour::Flaggable} in the class.
+  #
+  # @example
+  #   class User < ActiveRecord::Base
+  #     acts_as_taggable find_by: :email
+  #   end
+  #
+  # @option options [Symbol] :find_by The field to find the record by when
+  #   running rake tasks. Defaults to :id.
+  def acts_as_flaggable(options = {})
+    class_eval do
+      @detour_flaggable_find_by = :id
+
+      has_many :flaggable_flags,
+        as: :flaggable,
+        class_name: "Detour::FlaggableFlag"
+
+      has_many :opt_out_flags,
+        as: :flaggable,
+        class_name: "Detour::OptOutFlag"
+
+      has_many :features,
+        through: :flaggable_flags,
+        class_name: "Detour::Feature"
+
+      if options[:find_by]
+        @detour_flaggable_find_by = options[:find_by]
+      end
+
+      extend  Detour::Flaggable::ClassMethods
+      include Detour::Flaggable
+    end
+  end
+end

data/lib/detour/feature.rb

@@ -0,0 +1,312 @@
+# Represents an individual feature that may be rolled out to a set of records
+# via individual flags, percentages, or defined groups.
+class Detour::Feature < ActiveRecord::Base
+  # A hash representing the groups that have been defined.
+  @defined_groups = {}
+
+  # Directories to grep for feature tests
+  @grep_dirs  = []
+
+  self.table_name = :detour_features
+
+  has_many :flaggable_flags
+  has_many :group_flags
+  has_many :percentage_flags
+  has_many :opt_out_flags
+  has_many :flags, dependent: :destroy
+
+  validates :name, presence: true, uniqueness: true
+
+  attr_accessible :name
+
+  # Returns an instance variable intended to hold an array of the lines of code
+  # that this feature appears on.
+  #
+  # @return [Array<String>] The lines that this rollout appears on (if
+  #   {Detour::Feature.all_with_lines} has already been called).
+  def lines
+    @lines ||= []
+  end
+
+  # Determines whether or not the given instance has had the feature rolled out
+  # to it either via direct flagging-in, percentage, or by group membership.
+  #
+  # @example
+  #   feature.match?(current_user)
+  #
+  # @param [ActiveRecord::Base] instance A record to be tested for feature
+  #   rollout.
+  #
+  # @return Whether or not the given instance has the feature rolled out to it.
+  def match?(instance)
+    match_id?(instance) || match_percentage?(instance) || match_groups?(instance)
+  end
+
+  # Determines whether or not the given instance has had the feature rolled out
+  # to it via direct flagging-in.
+  #
+  # @example
+  #   feature.match_id?(current_user)
+  #
+  # @param [ActiveRecord::Base] instance A record to be tested for feature
+  #   rollout.
+  #
+  # @return Whether or not the given instance has the feature rolled out to it
+  #   via direct flagging-in.
+  def match_id?(instance)
+    flaggable_flags.where(flaggable_type: instance.class.to_s, flaggable_id: instance.id).any?
+  end
+
+  # Determines whether or not the given instance has had the feature rolled out
+  # to it via percentage.
+  #
+  # @example
+  #   feature.match_percentage?(current_user)
+  #
+  # @param [ActiveRecord::Base] instance A record to be tested for feature
+  #   rollout.
+  #
+  # @return Whether or not the given instance has the feature rolled out to it
+  #   via direct percentage.
+  def match_percentage?(instance)
+    flag = percentage_flags.find(:first, conditions: ["flaggable_type = ?", instance.class.to_s])
+    percentage = flag ? flag.percentage : 0
+
+    instance.id % 10 < percentage / 10
+  end
+
+  # Determines whether or not the given instance has had the feature rolled out
+  # to it via group membership.
+  #
+  # @example
+  #   feature.match_groups?(current_user)
+  #
+  # @param [ActiveRecord::Base] instance A record to be tested for feature
+  #   rollout.
+  #
+  # @return Whether or not the given instance has the feature rolled out to it
+  #   via direct group membership.
+  def match_groups?(instance)
+    klass = instance.class.to_s
+
+    return unless self.class.defined_groups[klass]
+
+    group_names = group_flags.find_all_by_flaggable_type(klass).collect(&:group_name)
+
+    self.class.defined_groups[klass].collect { |group_name, block|
+      block.call(instance) if group_names.include? group_name
+    }.any?
+  end
+
+  class << self
+    # Returns the defined groups.
+    def defined_groups
+      @defined_groups
+    end
+
+    # Returns the default flaggable class.
+    def default_flaggable_class_name
+      @default_flaggable_class_name
+    end
+
+    # Sets the default flaggable class.
+    def default_flaggable_class_name=(klass)
+      @default_flaggable_class_name = klass
+    end
+
+    # A list of directories to search through when finding feature checks.
+    def grep_dirs
+      @grep_dirs
+    end
+
+    # Set the list of directories to search through when finding feature checks.
+    def grep_dirs=(grep_dirs)
+      @grep_dirs = grep_dirs
+    end
+
+    # Return an array of both every feature in the database as well as every
+    # feature that is checked for in `@grep_dirs`. Features that are checked
+    # for but not persisted will be returned as unpersisted instances of this
+    # class. Each instance returned will have its `@lines` set to an array
+    # containing every line in `@grep_dirs` where it is checked for.
+    #
+    # @return [Array<Detour::Feature>] Every persisted and
+    #   checked-for feature.
+    def all_with_lines
+      obj = all.each_with_object({}) { |feature, obj| obj[feature.name] = feature }
+
+      Dir[*@grep_dirs].each do |path|
+        next if File.directory? path
+
+        File.open path do |file|
+          file.each_line.with_index(1) do |line, i|
+            line.scan(/\.has_feature\?\s*\(*:(\w+)/).each do |match|
+              match = match[0]
+              obj[match] ||= find_or_initialize_by_name(match)
+              obj[match].lines << "#{path}#L#{i}"
+            end
+          end
+        end
+      end
+
+      obj.values
+    end
+
+    # Add a record to the given feature. If the feature is not found, an
+    # ActiveRecord::RecordNotFound will be raised.
+    #
+    # @example
+    #   Detour::Feature.add_record_to_feature user, :new_ui
+    #
+    # @param [ActiveRecord::Base] record A record to add the feature to.
+    # @param [String,Symbol] feature_name The feature to be added to the record.
+    #
+    # @return [Detour::Flag] The
+    #   {Detour::Flag Flag} created.
+    def add_record_to_feature(record, feature_name)
+      feature = find_by_name!(feature_name)
+      feature.flaggable_flags.where(flaggable_type: record.class.to_s, flaggable_id: record.id).first_or_create!
+    end
+
+    # Remove a record from the given feature. If the feature is not found, an
+    # ActiveRecord::RecordNotFound will be raised.
+    #
+    # @example
+    #   Detour::Feature.remove_record_from_feature user, :new_ui
+    #
+    # @param [ActiveRecord::Base] record A record to remove the feature from.
+    # @param [String,Symbol] feature_name The feature to be removed from the
+    #   record.
+    def remove_record_from_feature(record, feature_name)
+      feature = find_by_name!(feature_name)
+      feature.flaggable_flags.where(flaggable_type: record.class.to_s, flaggable_id: record.id).destroy_all
+    end
+
+    # Opt the given record out of a feature. If the feature is not found, an
+    # ActiveRecord::RecordNotFound will be raised. An opt out ensures that no
+    # matter what, `record.rollout?(:rollout)` will always return false for any
+    # opted-out-of features.
+    #
+    # @param [ActiveRecord::Base] record A record to opt out of the feature.
+    # @param [String,Symbol] feature_name The feature to be opted out of.
+    #
+    # @example
+    #   Detour::Feature.opt_record_out_of_feature user, :new_ui
+    #
+    # @return [Detour::OptOut] The
+    #   {Detour::OptOut OptOut} created.
+    def opt_record_out_of_feature(record, feature_name)
+      feature = find_by_name!(feature_name)
+      feature.opt_out_flags.where(flaggable_type: record.class.to_s, flaggable_id: record.id).first_or_create!
+    end
+
+    # Remove any opt out for the given record out of a feature. If the feature
+    # is not found, an ActiveRecord::RecordNotFound will be raised.
+    #
+    # @example
+    #   Detour::Feature.un_opt_record_out_of_feature user, :new_ui
+    #
+    # @param [ActiveRecord::Base] record A record to un-opt-out of the feature.
+    # @param [String,Symbol] feature_name The feature to be un-opted-out of.
+    def un_opt_record_out_of_feature(record, feature_name)
+      feature = find_by_name!(feature_name)
+      feature.opt_out_flags.where(flaggable_type: record.class.to_s, flaggable_id: record.id).destroy_all
+    end
+
+    # Add a group to the given feature. If the feature is not found, an
+    # ActiveRecord::RecordNotFound will be raised.
+    #
+    # @example
+    #   Detour::Feature.add_group_to_feature "User", "admin", :delete_records
+    #
+    # @param [String] flaggable_type The class (as a string) that the group
+    #   should be associated with.
+    # @param [String] group_name The name of the group to have the feature
+    #   added to it.
+    # @param [String,Symbol] feature_name The feature to be added to the group.
+    #
+    # @return [Detour::Flag] The
+    #   {Detour::Flag Flag} created.
+    def add_group_to_feature(flaggable_type, group_name, feature_name)
+      feature = find_by_name!(feature_name)
+      feature.group_flags.where(flaggable_type: flaggable_type, group_name: group_name).first_or_create!
+    end
+
+    # Remove a group from agiven feature. If the feature is not found, an
+    # ActiveRecord::RecordNotFound will be raised.
+    #
+    # @example
+    #   Detour::Feature.remove_group_from_feature "User", "admin", :delete_records
+    #
+    # @param [String] flaggable_type The class (as a string) that the group should
+    #   be removed from.
+    # @param [String] group_name The name of the group to have the feature
+    #   removed from it.
+    # @param [String,Symbol] feature_name The feature to be removed from the
+    #   group.
+    def remove_group_from_feature(flaggable_type, group_name, feature_name)
+      feature = find_by_name!(feature_name)
+      feature.group_flags.where(flaggable_type: flaggable_type, group_name: group_name).destroy_all
+    end
+
+    # Add a percentage of records to the given feature. If the feature is not
+    # found, an ActiveRecord::RecordNotFound will be raised.
+    #
+    # @example
+    #   Detour::Feature.add_percentage_to_feature "User", 75, :delete_records
+    #
+    # @param [String] flaggable_type The class (as a string) that the percetnage
+    #   should be associated with.
+    # @param [Integer] percentage The percentage of `flaggable_type` records
+    #   that the feature will be available for.
+    # @param [String,Symbol] feature_name The feature to be added to the
+    #   percentage of records.
+    #
+    # @return [Detour::Flag] The
+    #   {Detour::Flag Flag} created.
+    def add_percentage_to_feature(flaggable_type, percentage, feature_name)
+      feature = find_by_name!(feature_name)
+
+      flag = feature.percentage_flags.where(flaggable_type: flaggable_type).first_or_initialize
+      flag.update_attributes!(percentage: percentage)
+    end
+
+    # Remove any percentage flags for the given feature. If the feature is not
+    # found, an ActiveRecord::RecordNotFound will be raised.
+    #
+    # @example
+    #   Detour::Feature.remove_percentage_from_feature "User", delete_records
+    #
+    # @param [String] flaggable_type The class (as a string) that the percetnage
+    #   should be removed from.
+    # @param [String,Symbol] feature_name The feature to have the percentage
+    #   flag removed from.
+    def remove_percentage_from_feature(flaggable_type, feature_name)
+      feature = find_by_name!(feature_name)
+      feature.percentage_flags.where(flaggable_type: flaggable_type).destroy_all
+    end
+
+    # Allows for methods of the form `define_user_group` that call the private
+    # method `define_group_for_class`. A new group for any `User` records will
+    # be created that rollouts can be attached to.
+    #
+    # @example
+    #   Detour::Feature.define_user_group :admins do |user|
+    #     user.admin?
+    #   end
+    def method_missing(method, *args, &block)
+      if /^define_(?<klass>[a-z0-9_]+)_group/ =~ method
+        define_group_for_class(klass.classify, args[0], &block)
+      else
+        super
+      end
+    end
+
+    private
+
+    def define_group_for_class(klass, group_name, &block)
+      @defined_groups[klass] ||= {}
+      @defined_groups[klass][group_name] = block
+    end
+  end
+end