flipper 0.3.0 → 0.4.0

data/.rspec

@@ -0,0 +1 @@
+--color

data/Changelog.md

@@ -0,0 +1,12 @@
+## 0.4.0
+
+* No longer use #id for detecting actors. You must now define #flipper_id on
+  anything that you would like to behave as an actor.
+* Strings are now used instead of Integers for Actor identifiers. More flexible
+  and the only reason I used Integers was to do modulo for percentage of actors.
+  Since percentage of actors now uses hashing, integer is no longer needed.
+* Easy integration of instrumentation with AS::Notifications or anything similar.
+* A bunch of stuff around inspecting and getting names/descriptions out of
+  things to more easily figure out what is going on.
+* Percentage of actors hash is now also seeded with feature name so the same
+  actors don't get all features instantly.

data/Gemfile

@@ -2,17 +2,14 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'rake'
+gem 'metriks', :require => false
+gem 'rspec'
+gem 'rack-test'
+gem 'activesupport', :require => false
 
 group(:guard) do
   gem 'guard'
   gem 'guard-rspec'
   gem 'guard-bundler'
-  gem 'terminal-notifier-guard'
   gem 'rb-fsevent'
 end
-
-group(:test) do
-  gem 'rspec'
-  gem 'rack-test'
-end
-

data/Guardfile

@@ -6,8 +6,20 @@ guard 'bundler' do
   watch(/^.+\.gemspec/)
 end
 
-guard 'rspec' do
-  watch(%r{^spec/.+_spec\.rb$}) { "spec" }
-  watch(%r{^lib/(.+)\.rb$}) { "spec" }
-  watch('spec/helper.rb')  { "spec" }
+rspec_options = {
+  :all_after_pass => false,
+  :all_on_start   => false,
+  :keep_failed    => false,
+}
+
+guard 'rspec', rspec_options do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{shared_adapter_specs\.rb$}) { |m|
+    [
+      "spec/flipper/adapters/memory_spec.rb",
+      "spec/flipper/adapters/memoized_spec.rb",
+    ]
+  }
+  watch('spec/helper.rb') { "spec" }
 end

data/README.md

@@ -2,23 +2,11 @@
 
 Feature flipping is the act of enabling or disabling features or parts of your application, ideally without re-deploying or changing anything in your code base.
 
-The goal of this gem is to make turning features on or off so easy that everyone does it. Whatever your data store, throughput, or experience, feature flipping should be easy and relatively no extra burden to your application.
-
-## Note
-
-This project is a work in progress and not ready for production yet, but will be very soon.
-
-## Why not use <insert gem name here, most likely rollout>?
-
-I've used rollout extensively in the past and it was fantastic. The main reason I reinvented the wheel to some extent is:
-
-* API - For whatever reason, I could never remember the API for rollout.
-* Adapter Based - Rather than force redis, if you can implement a few simple methods, you can use the data store of your choice to power your flippers (memory, file system, mongo, redis, sql, etc.). It is also dead simple to front your data store with memcache if you so desire since feature checking is read heavy, as opposed to write heavy.
+The goal of this gem is to make turning features on or off so easy that everyone does it. Whatever your data store, throughput, or experience, feature flipping should be easy and have minimal impact on your application.
 
 ## Coming Soon™
 
-* Web UI (think resque UI for features toggling/status)
-* Optimizations for per request in process caching of trips to the adapter
+* [Web UI](https://github.com/jnunemaker/flipper-ui) (think resque UI for features toggling/status)
 
 ## Usage
 
@@ -26,9 +14,9 @@ The goal of the API for flipper was to have everything revolve around features a
 
 ```ruby
 require 'flipper'
-require 'flipper/adapters/memory'
 
 # pick an adapter
+require 'flipper/adapters/memory'
 adapter = Flipper::Adapters::Memory.new
 
 # get a handy dsl instance
@@ -92,39 +80,56 @@ There is no requirement that the thing yielded to the block be a user model or w
 
 ### 3. Individual Actor
 
-Turn on for individual thing. Think enable feature for someone to test or for a buddy.
+Turn feature on for individual thing. Think enable feature for someone to test or for a buddy. The only requirement for an individual actor is that it must respond to `flipper_id`.
 
 ```ruby
 flipper = Flipper.new(adapter)
 
-# convert user or person or whatever to flipper actor for storing and checking
-actor = flipper.actor(user.id)
+flipper[:stats].enable user
+flipper[:stats].enabled? user # true
 
-flipper[:stats].enable actor
-flipper[:stats].enabled? actor # true
+flipper[:stats].disable user
+flipper[:stats].enabled? user # false
 
-flipper[:stats].disable actor
-flipper[:stats].disabled? actor # true
+# you can enable anything, does not need to be user or person
+flipper[:search].enable group
+flipper[:search].enabled? group
+```
+
+The key is to make sure you do not enable two different types of objects for the same feature. Imagine that user has a flipper_id of 6 and group has a flipper_id of 6. Enabling search for user would automatically enable it for group, as they both have a flipper_id of 6.
+
+The one exception to this rule is if you have globally unique flipper_ids, such as uuid's. If your flipper_ids are unique globally in your entire system, enabling two different types should be safe. Another way around this is to prefix the flipper_id with the class name like this:
+
+```ruby
+class User
+  def flipper_id
+    "User:#{id}"
+  end
+end
+
+class Group
+  def flipper_id
+    "Group:#{id}"
+  end
+end
 ```
 
 ### 4. Percentage of Actors
 
-Turn this on for a percentage of actors (think users or people). Consistently on or off for this user as long as percentage increases. Think slow rollout of a new feature to users.
+Turn this on for a percentage of actors (think user, member, account, group, whatever). Consistently on or off for this user as long as percentage increases. Think slow rollout of a new feature to a percentage of things.
 
 ```ruby
 flipper = Flipper.new(adapter)
 
-# convert user or person or whatever to flipper actor for checking if in percentage
-actor = flipper.actor(user.id)
-
 # returns a percentage of actors instance set to 10
 percentage = flipper.actors(10)
 
 # turn stats on for 10 percent of users in the system
 flipper[:stats].enable percentage
 
-# checks if actor's identifier is in the enabled percentage
-flipper[:stats].enabled? actor
+# checks if actor's flipper_id is in the enabled percentage by hashing
+# user.flipper_id.to_s to ensure enabled distribution is smooth
+flipper[:stats].enabled? user
 
 ```
 
@@ -144,24 +149,48 @@ percentage = flipper.random(5)
 flipper[:logging].enable percentage
 ```
 
-Randomness is probably not a good idea for enabling new features in the UI. Most of the time you want a feature on or off for a user, but there are definitely times when I have found percentage of random to be very useful.
-
+Randomness is not a good idea for enabling new features in the UI. Most of the time you want a feature on or off for a user, but there are definitely times when I have found percentage of random to be very useful.
 
 ## Adapters
 
-I plan on supporting in-memory, Mongo, and Redis as adapters for flipper. Others are welcome so please let me know if you create one.
+I plan on supporting [in-memory](https://github.com/jnunemaker/flipper/blob/master/lib/flipper/adapters/memory.rb), [Mongo](https://github.com/jnunemaker/flipper-mongo), and [Redis](https://github.com/jnunemaker/flipper-redis) as adapters for flipper. Others are welcome so please let me know if you create one.
 
 ### Memory
 
-You can use this for tests if you want. That is pretty much all I use it for.
+You can use the [in-memory adapter](https://github.com/jnunemaker/flipper/blob/master/lib/flipper/adapters/memory.rb) for tests if you want. That is pretty much all I use it for.
 
 ### Mongo
 
-Currently, the mongo adapter stores everything in a single document. This is cool as if you cache that document for the life of a web request or whatever, you can check a ton of features by adding very little burden (1 query per request).
+Currently, the [mongo adapter](https://github.com/jnunemaker/flipper-mongo) comes in two flavors.
+
+The [vanilla mongo adapter](https://github.com/jnunemaker/flipper-mongo/blob/master/lib/flipper/adapters/mongo.rb) stores each key in its own document. This means for each gate checked per feature there will be a query to mongo.
+
+Personally, the adapter I prefer is the [single document adapter](https://github.com/jnunemaker/flipper-mongo/blob/master/lib/flipper/adapters/mongo_single_document.rb), which stores all features and gates in a single document. If you combine this adapter with the [local cache middleware](https://github.com/jnunemaker/flipper/blob/master/lib/flipper/middleware/local_cache.rb), the document will only be queried once per request, which is pretty awesome.
 
 ### Redis
 
-Redis is great for this type of stuff and it only took a few minutes to implement. The only real problem with redis right now is that automated failover isn't that easy so relying on it for every code path in my app would make me nervous.
+Redis is great for this type of stuff and it only took a few minutes to implement a [redis adapter](https://github.com/jnunemaker/flipper-redis). The only real problem with redis right now is that automated failover isn't that easy so relying on it for every code path in my app would make me nervous.
+
+## Optimization
+
+One optimization that flipper provides is a local cache. Once you have a flipper instance you can use the local cache to store each adapter key lookup in memory for as long as you want.
+
+Out of the box there is a middleware that will store each key lookup for the duration of the request. This means you will only actually query your adapter's data store once per feature per gate that is checked. You can use the middleware from a Rails initializer like so:
+
+```ruby
+require 'flipper/middleware/local_cache'
+
+# create flipper dsl instance, see above examples for more details
+flipper = Flipper.new(...)
+
+# ensure entire request is wrapped, `use` would probably be ok instead of
+# `insert_after`, but I noticed that Rails used `insert_after` for their
+# identity map, which this is akin to, and figured it was for a reason.
+Rails.application.config.middleware.insert_after \
+  ActionDispatch::Callbacks,
+  Flipper::Middleware::LocalCache,
+  flipper
+```
 
 ## Installation
 

data/examples/basic.rb

@@ -1,4 +1,4 @@
-require './example_setup'
+require File.expand_path('../example_setup', __FILE__)
 
 require 'flipper'
 require 'flipper/adapters/memory'

data/examples/dsl.rb

@@ -1,4 +1,4 @@
-require './example_setup'
+require File.expand_path('../example_setup', __FILE__)
 
 require 'flipper'
 require 'flipper/adapters/memory'
@@ -13,6 +13,9 @@ class Person
   def initialize(id)
     @id = id
   end
+
+  # Must respond to flipper_id
+  alias_method :flipper_id, :id
 end
 
 person = Person.new(1)
@@ -53,9 +56,7 @@ flipper.disable :stats
 stats.disable
 
 puts "stats.enabled?: #{stats.enabled?}"
-puts "stats.disabled?: #{stats.disabled?}"
 puts "stats.enabled? person: #{stats.enabled? person}"
-puts "stats.disabled? person: #{stats.disabled? person}"
 puts
 
 # get an instance of the percentage of random type set to 5
@@ -64,16 +65,13 @@ puts flipper.random(5).inspect
 # get an instance of the percentage of actors type set to 15
 puts flipper.actors(15).inspect
 
-# get an instance of an actor using an object that responds to id
-responds_to_id = Struct.new(:id).new(10)
-puts flipper.actor(responds_to_id).inspect
-
-# get an instance of an actor using an object that responds to identifier
-responds_to_identifier = Struct.new(:identifier).new(11)
-puts flipper.actor(responds_to_identifier).inspect
+# get an instance of an actor using an object that responds to flipper_id
+responds_to_flipper_id = Struct.new(:flipper_id).new(10)
+puts flipper.actor(responds_to_flipper_id).inspect
 
-# get an instance of an actor using a number
-puts flipper.actor(23).inspect
+# get an instance of an actor using an object
+thing = Struct.new(:flipper_id).new(22)
+puts flipper.actor(thing).inspect
 
 # register a top level group
 admins = Flipper.register(:admins) { |actor|

data/examples/group.rb

@@ -1,4 +1,4 @@
-require './example_setup'
+require File.expand_path('../example_setup', __FILE__)
 
 require 'flipper'
 require 'flipper/adapters/memory'
@@ -14,17 +14,23 @@ end
 
 # Some class that represents actor that will be trying to do something
 class User
-  def initialize(admin)
+  attr_reader :id
+
+  def initialize(id, admin)
+    @id = id
     @admin = admin
   end
 
+  # Must respond to flipper_id
+  alias_method :flipper_id, :id
+
   def admin?
     @admin == true
   end
 end
 
-admin = User.new(true)
-non_admin = User.new(false)
+admin = User.new(1, true)
+non_admin = User.new(2, false)
 
 puts "Stats for admin: #{stats.enabled?(admin)}"
 puts "Stats for non_admin: #{stats.enabled?(non_admin)}"

data/examples/individual_actor.rb

@@ -1,4 +1,4 @@
-require './example_setup'
+require File.expand_path('../example_setup', __FILE__)
 
 require 'flipper'
 require 'flipper/adapters/memory'
@@ -14,16 +14,19 @@ class User
   def initialize(id)
     @id = id
   end
+
+  # Must respond to flipper_id
+  alias_method :flipper_id, :id
 end
 
 user1 = User.new(1)
 user2 = User.new(2)
 
-puts "Stats for user1: #{stats.enabled?(flipper.actor(user1))}"
-puts "Stats for user2: #{stats.enabled?(flipper.actor(user2))}"
+puts "Stats for user1: #{stats.enabled?(user1)}"
+puts "Stats for user2: #{stats.enabled?(user2)}"
 
 puts "\nEnabling stats for user1...\n\n"
-stats.enable(flipper.actor(user1))
+stats.enable(user1)
 
-puts "Stats for user1: #{stats.enabled?(flipper.actor(user1))}"
-puts "Stats for user2: #{stats.enabled?(flipper.actor(user2))}"
+puts "Stats for user1: #{stats.enabled?(user1)}"
+puts "Stats for user2: #{stats.enabled?(user2)}"

data/examples/instrumentation.rb

@@ -0,0 +1,39 @@
+require File.expand_path('../example_setup', __FILE__)
+
+require 'securerandom'
+require 'active_support/notifications'
+
+class FlipperSubscriber
+  def call(*args)
+    event = ActiveSupport::Notifications::Event.new(*args)
+    puts event.inspect
+  end
+
+  ActiveSupport::Notifications.subscribe(/flipper/, new)
+end
+
+require 'flipper'
+require 'flipper/adapters/memory'
+
+# pick an adapter
+adapter = Flipper::Adapters::Memory.new
+
+# get a handy dsl instance
+flipper = Flipper.new(adapter, :instrumenter => ActiveSupport::Notifications)
+
+# grab a feature
+search = flipper[:search]
+
+perform = lambda do
+  # check if that feature is enabled
+  if search.enabled?
+    puts 'Search away!'
+  else
+    puts 'No search for you!'
+  end
+end
+
+perform.call
+puts 'Enabling Search...'
+search.enable
+perform.call

data/examples/percentage_of_actors.rb

@@ -1,4 +1,4 @@
-require './example_setup'
+require File.expand_path('../example_setup', __FILE__)
 
 require 'flipper'
 require 'flipper/adapters/memory'
@@ -14,22 +14,25 @@ class User
   def initialize(id)
     @id = id
   end
+
+  # Must respond to flipper_id
+  alias_method :flipper_id, :id
 end
 
 pitt = User.new(1)
 clooney = User.new(10)
 
-puts "Stats for pitt: #{stats.enabled?(flipper.actor(pitt))}"
-puts "Stats for clooney: #{stats.enabled?(flipper.actor(clooney))}"
+puts "Stats for pitt: #{stats.enabled?(pitt)}"
+puts "Stats for clooney: #{stats.enabled?(clooney)}"
 
 puts "\nEnabling stats for 5 percent...\n\n"
 stats.enable(Flipper::Types::PercentageOfActors.new(5))
 
-puts "Stats for pitt: #{stats.enabled?(flipper.actor(pitt))}"
-puts "Stats for clooney: #{stats.enabled?(flipper.actor(clooney))}"
+puts "Stats for pitt: #{stats.enabled?(pitt)}"
+puts "Stats for clooney: #{stats.enabled?(clooney)}"
 
-puts "\nEnabling stats for 15 percent...\n\n"
-stats.enable(Flipper::Types::PercentageOfActors.new(15))
+puts "\nEnabling stats for 50 percent...\n\n"
+stats.enable(Flipper::Types::PercentageOfActors.new(50))
 
-puts "Stats for pitt: #{stats.enabled?(flipper.actor(pitt))}"
-puts "Stats for clooney: #{stats.enabled?(flipper.actor(clooney))}"
+puts "Stats for pitt: #{stats.enabled?(pitt)}"
+puts "Stats for clooney: #{stats.enabled?(clooney)}"

data/examples/percentage_of_random.rb

@@ -1,4 +1,4 @@
-require './example_setup'
+require File.expand_path('../example_setup', __FILE__)
 
 require 'flipper'
 require 'flipper/adapters/memory'
@@ -25,9 +25,11 @@ perform_test = lambda do |number|
   actual = (enabled.size / total.to_f * 100).round(2)
 
   # puts "#{enabled.size} / #{total}"
-  puts "percentage: #{actual} vs #{number}"
+  puts "percentage: #{actual.to_s.rjust(6, ' ')} vs #{number.to_s.rjust(3, ' ')}"
 end
 
+puts "percentage: Actual vs Hoped For"
+
 [1, 5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100].each do |number|
   perform_test.call number
 end

data/lib/flipper.rb

@@ -1,26 +1,59 @@
 module Flipper
-  def self.new(*args)
-    DSL.new(*args)
-  end
-
-  def self.groups
-    @groups ||= Registry.new
-  end
+  # Private: The namespace for all instrumented events.
+  InstrumentationNamespace = :flipper
 
-  def self.groups=(registry)
-    @groups = registry
+  # Public: Start here. Given an adapter returns a handy DSL to all the flipper
+  # goodness. To see supported options, check out dsl.rb.
+  def self.new(adapter, options = {})
+    DSL.new(adapter, options)
   end
 
+  # Public: Use this to register a group by name.
+  #
+  # name - The Symbol name of the group.
+  # block - The block that should be used to determine if the group matches a
+  #         given thing.
+  #
+  # Examples
+  #
+  #   Flipper.registry(:admins) { |thing|
+  #     thing.respond_to?(:admin?) && thing.admin?
+  #   }
+  #
+  # Returns a Flipper::Group.
+  # Raises Flipper::DuplicateGroup if the group is already registered.
   def self.register(name, &block)
     group = Types::Group.new(name, &block)
     groups.add(group.name, group)
     group
   rescue Registry::DuplicateKey
-    raise DuplicateGroup, %Q{Group named "#{name}" is already registered}
+    raise DuplicateGroup, %Q{Group #{name.inspect} has already been registered}
   end
 
+  # Internal: Fetches a group by name.
+  #
+  # name - The Symbol name of the group.
+  #
+  # Examples
+  #
+  #   Flipper.group(:admins)
+  #
+  # Returns the Flipper::Group if group registered.
+  # Raises Flipper::GroupNotRegistered if group is not registered.
   def self.group(name)
     groups.get(name)
+  rescue Flipper::Registry::KeyNotFound => e
+    raise GroupNotRegistered, "Group #{e.key.inspect} has not been registered"
+  end
+
+  # Internal: Registry of all groups.
+  def self.groups
+    @groups ||= Registry.new
+  end
+
+  # Internal: Change the groups registry.
+  def self.groups=(registry)
+    @groups = registry
   end
 end