detour 0.0.1

data/lib/detour/flag.rb

@@ -0,0 +1,13 @@
+# Indicates that a specific feature has been rolled out to an individual
+# Table for storing flaggable flag-ins, group flag-ins, or percentage-based
+# flag-ins.
+class Detour::Flag < ActiveRecord::Base
+  self.table_name = :detour_flags
+
+  belongs_to :feature
+
+  validates :feature_id, presence: true
+  validates :flaggable_type, presence: true
+
+  attr_accessible :flaggable_type
+end

data/lib/detour/flaggable.rb

@@ -0,0 +1,66 @@
+module Detour::Flaggable
+  module ClassMethods
+    # Finds a record by the field set by the :find_by param in
+    # `acts_as_flaggable`. If no :find_by param was provided, :id is used.
+    #
+    # @param [String,Integer] value The value to find the record by.
+    def flaggable_find!(value)
+      send("find_by_#{@detour_flaggable_find_by}!", value)
+    end
+  end
+
+  # Returns whether or not the object has access to the given feature. If given
+  # a block, it will call the block if the user has access to the feature.
+  #
+  # If an exception is raised in the block, it will increment the
+  # `failure_count` of the feature and raise the exception.
+  #
+  # @example
+  #   # Exceptions will be tracked in the `failure_count` of :new_user_interface.
+  #   user.has_feature?(:new_user_interface) do
+  #     # ...
+  #   end
+  #
+  # @example
+  #   # Exceptions will *not* be tracked in the `failure_count` of :new_user_interface.
+  #   if user.has_feature?(:new_user_interface)
+  #     # ...
+  #   end
+  #
+  # @param [Symbol] feature_name The name of the
+  #   {Detour::Feature Feature} being checked.
+  # @param [Proc] &block A block to be called if the user is flagged in to the
+  #   feature.
+  def has_feature?(feature_name, &block)
+    if detour_features.include? feature_name.to_s
+      match = true
+    else
+      feature = Detour::Feature.find_by_name(feature_name)
+      return false unless feature
+
+      opt_out = opt_out_flags.find_by_feature_id(feature.id)
+      return false if opt_out
+
+      match = feature.match? self
+
+      if match
+        detour_features << feature.name.to_s
+      end
+    end
+
+    if match && block_given?
+      begin
+        yield
+      rescue => e
+        feature.increment! :failure_count
+        raise e
+      end
+    end
+
+    match
+  end
+
+  def detour_features
+    @detour_features ||= []
+  end
+end

data/lib/detour/flaggable_flag.rb

@@ -0,0 +1,10 @@
+# An individual record of a certain type may be flagged into a feature with
+# this class.
+class Detour::FlaggableFlag < Detour::Flag
+  belongs_to :flaggable, polymorphic: true
+
+  validates :flaggable_id, presence: true
+  validates :feature_id, uniqueness: { scope: [:flaggable_type, :flaggable_id] }
+
+  attr_accessible :flaggable
+end

data/lib/detour/group_flag.rb

@@ -0,0 +1,8 @@
+# A group of flaggable records of a given class may be flagged into a feature
+# with this class.
+class Detour::GroupFlag < Detour::Flag
+  validates :group_name, presence: true
+
+  attr_accessible :group_name
+  validates :feature_id, uniqueness: { scope: [:flaggable_type, :group_name] }
+end

data/lib/detour/opt_out_flag.rb

@@ -0,0 +1,10 @@
+# Ensures that a feature will never be available to the associated record,
+# even in the case of, for example, a 100% flag.
+class Detour::OptOutFlag < Detour::Flag
+  belongs_to :flaggable, polymorphic: true
+
+  validates :flaggable_id, presence: true
+  validates :feature_id, uniqueness: { scope: [:flaggable_type, :flaggable_id] }
+
+  attr_accessible :flaggable
+end

data/lib/detour/percentage_flag.rb

@@ -0,0 +1,11 @@
+# A percentage of flaggable records of a given class may be flagged into a feature
+# with this class.
+class Detour::PercentageFlag < Detour::Flag
+  validates :percentage,
+    presence: true,
+    numericality: { greater_than: 0, less_than_or_equal_to: 100 }
+
+  validates :feature_id, uniqueness: { scope: :flaggable_type }
+
+  attr_accessible :percentage
+end

data/lib/detour/version.rb

@@ -0,0 +1,3 @@
+module Detour
+  VERSION = "0.0.1"
+end

data/lib/detour.rb

@@ -0,0 +1,35 @@
+require "active_record"
+require "detour/version"
+require "detour/feature"
+require "detour/flag"
+require "detour/flaggable_flag"
+require "detour/group_flag"
+require "detour/percentage_flag"
+require "detour/opt_out_flag"
+require "detour/flaggable"
+require "detour/acts_as_flaggable"
+
+module Detour
+  # Allows for configuration of Detour::Feature, mostly intended
+  # for defining groups:
+  #
+  # @example
+  #   Detour.configure do |config|
+  #     config.define_user_group :admins do |user|
+  #       user.admin?
+  #     end
+  #   end
+  def self.configure(&block)
+    yield Detour::Feature
+  end
+end
+
+class Detour::Task < Rails::Railtie
+  rake_tasks do
+    Dir[File.join(File.dirname(__FILE__), '../tasks/*.rake')].each { |f| load f }
+  end
+end
+
+if defined?(ActiveRecord::Base)
+  ActiveRecord::Base.extend Detour::ActsAsFlaggable
+end

data/lib/generators/active_record_rollout_generator.rb

@@ -0,0 +1,20 @@
+require "detour"
+require "rails/generators"
+require "rails/generators/active_record"
+
+class DetourGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  extend ActiveRecord::Generators::Migration
+
+  source_root File.expand_path("../templates", __FILE__)
+
+  desc "Creates migration for Detour"
+  def create_migration_file
+    migration_template "migration.rb", "db/migrate/setup_detour.rb"
+  end
+
+  desc "Sets up an initializer for Detour"
+  def create_initializer
+    copy_file "detour.rb", "config/initializers/detour.rb"
+  end
+end

data/lib/generators/templates/active_record_rollout.rb

@@ -0,0 +1,5 @@
+Detour.configure do |config|
+  # config.define_user_group :admins do |user|
+  #   user.admin?
+  # end
+end

data/lib/generators/templates/migration.rb

@@ -0,0 +1,30 @@
+class SetupDetour < ActiveRecord::Migration
+  def change
+    create_table :detour_features do |t|
+      t.string :name
+      t.integer :failure_count, default: 0
+      t.timestamps
+    end
+
+    add_index :detour_features, :name, unique: true
+
+    create_table :detour_flags do |t|
+      t.string  :type
+      t.integer :feature_id
+      t.integer :flaggable_id
+      t.string  :flaggable_type
+      t.string  :group_name
+      t.integer :percentage
+      t.timestamps
+    end
+
+    add_index :detour_flags, :type
+    add_index :detour_flags, :feature_id
+    add_index :detour_flags,
+      [:type, :feature_id, :flaggable_type, :flaggable_id],
+      name: "flag_type_feature_flaggable_type_id"
+    add_index :detour_flags,
+      [:type, :feature_id, :flaggable_type],
+    name: "flag_type_feature_flaggable_type"
+  end
+end

data/lib/tasks/detour.rake

@@ -0,0 +1,119 @@
+namespace :detour do
+  desc "Create a feature"
+  task :create, [:feature] => :environment do |task, args|
+    Detour::Feature.find_or_create_by_name! args[:feature]
+  end
+
+  desc "Destroy a feature"
+  task :destroy, [:feature] => :environment do |task, args|
+    feature = Detour::Feature.find_by_name! args[:feature]
+    feature.destroy
+  end
+
+  desc "Activate a feature for a record"
+  task :activate, [:feature, :flaggable_type, :flaggable_id] => :environment do |task, args|
+    if args.to_a.length < 3 && Detour::Feature.default_flaggable_class_name
+      klass = Detour::Feature.default_flaggable_class_name.constantize
+      record_locator = args[:flaggable_type]
+    else
+      klass = args[:flaggable_type].constantize
+      record_locator = args[:flaggable_id]
+    end
+
+    record = klass.flaggable_find! record_locator
+
+    Detour::Feature.add_record_to_feature record, args[:feature]
+  end
+
+  desc "Deactivate a feature for a record"
+  task :deactivate, [:feature, :flaggable_type, :flaggable_id] => :environment do |task, args|
+    if args.to_a.length < 3 && Detour::Feature.default_flaggable_class_name
+      klass = Detour::Feature.default_flaggable_class_name.constantize
+      record_locator = args[:flaggable_type]
+    else
+      klass = args[:flaggable_type].constantize
+      record_locator = args[:flaggable_id]
+    end
+
+    record = klass.flaggable_find! record_locator
+    Detour::Feature.remove_record_from_feature record, args[:feature]
+  end
+
+  desc "Opt a record out of a feature"
+  task :opt_out, [:feature, :flaggable_type, :flaggable_id] => :environment do |task, args|
+    if args.to_a.length < 3 && Detour::Feature.default_flaggable_class_name
+      klass = Detour::Feature.default_flaggable_class_name.constantize
+      record_locator = args[:flaggable_type]
+    else
+      klass = args[:flaggable_type].constantize
+      record_locator = args[:flaggable_id]
+    end
+
+    record = klass.flaggable_find! record_locator
+    Detour::Feature.opt_record_out_of_feature record, args[:feature]
+  end
+
+  desc "Remove an opt out of a record from a feature"
+  task :un_opt_out, [:feature, :flaggable_type, :flaggable_id] => :environment do |task, args|
+    if args.to_a.length < 3 && Detour::Feature.default_flaggable_class_name
+      klass = Detour::Feature.default_flaggable_class_name.constantize
+      record_locator = args[:flaggable_type]
+    else
+      klass = args[:flaggable_type].constantize
+      record_locator = args[:flaggable_id]
+    end
+
+    record = klass.flaggable_find! record_locator
+    Detour::Feature.un_opt_record_out_of_feature record, args[:feature]
+  end
+
+  desc "Activate a feature for a group"
+  task :activate_group, [:feature, :flaggable_type, :group_name] => :environment do |task, args|
+    if args.to_a.length < 3 && Detour::Feature.default_flaggable_class_name
+      klass = Detour::Feature.default_flaggable_class_name
+      group_name = args[:flaggable_type]
+    else
+      klass = args[:flaggable_type]
+      group_name = args[:group_name]
+    end
+
+    Detour::Feature.add_group_to_feature klass, group_name, args[:feature]
+  end
+
+  desc "Deactivate a feature for a group"
+  task :deactivate_group, [:feature, :flaggable_type, :group_name] => :environment do |task, args|
+    if args.to_a.length < 3 && Detour::Feature.default_flaggable_class_name
+      klass = Detour::Feature.default_flaggable_class_name
+      group_name = args[:flaggable_type]
+    else
+      klass = args[:flaggable_type]
+      group_name = args[:group_name]
+    end
+
+    Detour::Feature.remove_group_from_feature klass, group_name, args[:feature]
+  end
+
+  desc "Activate a feature for a percentage"
+  task :activate_percentage, [:feature, :flaggable_type, :percentage] => :environment do |task, args|
+    if args.to_a.length < 3 && Detour::Feature.default_flaggable_class_name
+      klass = Detour::Feature.default_flaggable_class_name
+      percentage = args[:flaggable_type]
+    else
+      klass = args[:flaggable_type]
+      percentage = args[:percentage]
+    end
+
+    Detour::Feature.add_percentage_to_feature klass, percentage.to_i, args[:feature]
+  end
+
+  desc "Deactivate a feature for a percentage"
+  task :deactivate_percentage, [:feature, :flaggable_type] => :environment do |task, args|
+    if args.to_a.length < 3 && Detour::Feature.default_flaggable_class_name
+      klass = Detour::Feature.default_flaggable_class_name
+    else
+      klass = args[:flaggable_type]
+    end
+
+    Detour::Feature.remove_percentage_from_feature klass, args[:feature]
+  end
+end

data/spec/integration/flag_rollout_spec.rb

@@ -0,0 +1,27 @@
+require "spec_helper"
+
+describe "flag rollouts" do
+  let(:user) { User.create }
+  let(:feature) { Detour::Feature.create(name: "foo") }
+
+  describe "creating a flag rollout" do
+    before do
+      Detour::Feature.add_record_to_feature user, feature.name
+    end
+
+    it "sets the feature on the user" do
+      feature.match_id?(user).should be_true
+    end
+  end
+
+  describe "removing a flag rollout" do
+    before do
+      Detour::Feature.add_record_to_feature user, feature.name
+      Detour::Feature.remove_record_from_feature user, feature.name
+    end
+
+    it "removes the feature from the user" do
+      feature.match_id?(user).should be_false
+    end
+  end
+end

data/spec/integration/group_rollout_spec.rb

@@ -0,0 +1,20 @@
+require "spec_helper"
+
+describe "group rollouts" do
+  let(:user) { User.create(name: "foo") }
+  let(:feature) { Detour::Feature.create(name: "foo") }
+  let!(:flag) { feature.group_flags.create(flaggable_type: "User", group_name: "foo_users") }
+
+  describe "creating a group rollout" do
+    before do
+      Detour::Feature.define_user_group "foo_users" do |user|
+        user.name == "foo"
+      end
+    end
+
+    it "sets the feature on the user" do
+      feature.match_groups?(user).should be_true
+    end
+  end
+end
+

data/spec/integration/percentage_rollout_spec.rb

@@ -0,0 +1,13 @@
+require "spec_helper"
+
+describe "percentage rollouts" do
+  let(:users) { 10.times.collect { User.create } }
+  let(:feature) { Detour::Feature.create(name: "foo") }
+  let!(:flag) { feature.percentage_flags.create(flaggable_type: "User", percentage: 20) }
+
+  describe "creating a percentage rollout" do
+    it "makes the feature available to the given percentage of instances" do
+      users.select { |user| feature.match_percentage?(user) }.length.should eq users.length / 5
+    end
+  end
+end

data/spec/lib/active_record/rollout/acts_as_flaggable_spec.rb

@@ -0,0 +1,31 @@
+require "spec_helper"
+
+describe Detour::ActsAsFlaggable do
+  subject { User.new }
+
+  it { should have_many :flaggable_flags }
+  it { should have_many :opt_out_flags }
+  it { should have_many(:features).through(:flaggable_flags) }
+
+  it "includes Detour::Flaggable" do
+    subject.class.ancestors.should include Detour::Flaggable
+  end
+
+  describe "#acts_as_flaggable" do
+    context "when given a :find_by parameter" do
+      class Foo < ActiveRecord::Base
+        acts_as_flaggable find_by: :email
+      end
+
+      it "sets the appropriate class variable on the class" do
+        Foo.instance_variable_get("@detour_flaggable_find_by").should eq :email
+      end
+    end
+
+    context "when not given a :find_by parameter" do
+      it "uses the default :id value for flaggable_find_by" do
+        User.instance_variable_get("@detour_flaggable_find_by").should eq :id
+      end
+    end
+  end
+end