flipper 0.4.0 → 0.5.0

data/Guardfile

@@ -13,13 +13,8 @@ rspec_options = {
 }
 
 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(%r{^spec/.+_spec\.rb$}) { "spec" }
+  watch(%r{^lib/(.+)\.rb$}) { "spec" }
+  watch(%r{shared_adapter_specs\.rb$}) { "spec" }
   watch('spec/helper.rb') { "spec" }
 end

data/README.md

@@ -4,6 +4,20 @@ Feature flipping is the act of enabling or disabling features or parts of your a
 
 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.
 
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'flipper'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself with:
+
+    $ gem install flipper
+
 ## Coming Soon™
 
 * [Web UI](https://github.com/jnunemaker/flipper-ui) (think resque UI for features toggling/status)
@@ -155,56 +169,30 @@ Randomness is not a good idea for enabling new features in the UI. Most of the t
 
 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 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](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 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.
+* [memory adapter](https://github.com/jnunemaker/flipper/blob/master/lib/flipper/adapters/memory.rb) - Great for tests.
+* [mongo adapter](https://github.com/jnunemaker/flipper-mongo)
+* [redis adapter](https://github.com/jnunemaker/flipper-redis)
+* [cassanity adapter](https://github.com/jnunemaker/flipper-cassanity)
 
 ## 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.
+One optimization that flipper provides is a memoizing middleware. The memoizing middleware ensures that you only make one adapter call per feature per request.
 
-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:
+This means if you check the same feature over and over, it will only make one mongo, redis, or whatever call per feature for the length of the request.
+
+You can use the middleware from a Rails initializer like so:
 
 ```ruby
-require 'flipper/middleware/local_cache'
+require 'flipper/middleware/memoizer'
 
 # 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
+# add the middleware
+Rails.application.config.middleware.use Flipper::Middleware::Memoizer, flipper
 ```
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'flipper'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself with:
-
-    $ gem install flipper
+**Note**: Be sure that the middlware is high enough up in your stack that all feature checks are wrapped.
 
 ## Contributing
 

data/examples/percentage_of_actors.rb

@@ -19,20 +19,25 @@ class User
   alias_method :flipper_id, :id
 end
 
-pitt = User.new(1)
-clooney = User.new(10)
+total = 10_000
 
-puts "Stats for pitt: #{stats.enabled?(pitt)}"
-puts "Stats for clooney: #{stats.enabled?(clooney)}"
+# create array of fake users
+users = (1..total).map { |n| User.new(n) }
 
-puts "\nEnabling stats for 5 percent...\n\n"
-stats.enable(Flipper::Types::PercentageOfActors.new(5))
+perform_test = lambda { |number|
+  flipper[:stats].enable flipper.actors(number)
 
-puts "Stats for pitt: #{stats.enabled?(pitt)}"
-puts "Stats for clooney: #{stats.enabled?(clooney)}"
+  enabled = users.map { |user|
+    flipper[:stats].enabled?(user) ? true : nil
+  }.compact
 
-puts "\nEnabling stats for 50 percent...\n\n"
-stats.enable(Flipper::Types::PercentageOfActors.new(50))
+  actual = (enabled.size / total.to_f * 100).round(2)
 
-puts "Stats for pitt: #{stats.enabled?(pitt)}"
-puts "Stats for clooney: #{stats.enabled?(clooney)}"
+  puts "percentage: #{actual.to_s.rjust(6, ' ')} vs #{number.to_s.rjust(3, ' ')}"
+}
+
+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/examples/percentage_of_random.rb

@@ -14,13 +14,9 @@ perform_test = lambda do |number|
   enabled = []
   disabled = []
 
-  (1..total).each do |number|
-    if logging.enabled?
-      enabled << number
-    else
-      disabled << number
-    end
-  end
+  enabled = (1..total).map { |n|
+    logging.enabled? ? true : nil
+  }.compact
 
   actual = (enabled.size / total.to_f * 100).round(2)
 

data/lib/flipper.rb

@@ -30,6 +30,13 @@ module Flipper
     raise DuplicateGroup, %Q{Group #{name.inspect} has already been registered}
   end
 
+  # Public: Clears the group registry.
+  #
+  # Returns nothing.
+  def self.unregister_groups
+    groups.clear
+  end
+
   # Internal: Fetches a group by name.
   #
   # name - The Symbol name of the group.
@@ -57,10 +64,10 @@ module Flipper
   end
 end
 
+require 'flipper/adapter'
 require 'flipper/dsl'
 require 'flipper/errors'
 require 'flipper/feature'
 require 'flipper/gate'
 require 'flipper/registry'
-require 'flipper/toggle'
 require 'flipper/type'

data/lib/flipper/adapter.rb

@@ -1,211 +1,5 @@
-require 'flipper/instrumenters/noop'
-
 module Flipper
-  # Internal: Adapter wrapper that wraps vanilla adapter instances. Adds things
-  # like local caching and convenience methods for adding/reading features from
-  # the adapter.
-  #
-  # So what is this local cache crap?
-  #
-  # The main goal of the local cache is to prevent multiple queries to an
-  # adapter for the same key for a given amount of time (per request, per
-  # background job, etc.).
-  #
-  # To facilitate with this, there is an included local cache middleware
-  # that enables local caching for the length of a web request. The local
-  # cache is enabled and cleared before each request and cleared and reset
-  # to original value after each request.
-  #
-  # Examples
-  #
-  # To see an example adapter that this would wrap, checkout the [memory
-  # adapter included with flipper](https://github.com/jnunemaker/flipper/blob/master/lib/flipper/adapters/memory.rb).
-  class Adapter
-    # Private: The name of instrumentation events.
-    InstrumentationName = "adapter_operation.#{InstrumentationNamespace}"
-
-    # Private: The name of the key that stores the set of known features.
-    FeaturesKey = 'features'
-
-    # Internal: Wraps vanilla adapter instance for use internally in flipper.
-    #
-    # object - Either an instance of Flipper::Adapter or a vanilla adapter instance
-    #
-    # Examples
-    #
-    #   adapter = Flipper::Adapters::Memory.new
-    #   instance = Flipper::Adapter.new(adapter)
-    #
-    #   Flipper::Adapter.wrap(instance)
-    #   # => Flipper::Adapter instance
-    #
-    #   Flipper::Adapter.wrap(adapter)
-    #   # => Flipper::Adapter instance
-    #
-    # Returns Flipper::Adapter instance
-    def self.wrap(object, options = {})
-      if object.is_a?(Flipper::Adapter)
-        object
-      else
-        new(object, options)
-      end
-    end
-
-    # Private: What adapter is being wrapped and will ultimately be used.
-    attr_reader :adapter
-
-    # Private: The name of the adapter. Based on the class name.
-    attr_reader :name
-
-    # Private: What is used to store the local cache.
-    attr_reader :local_cache
-
-    # Private: What is used to instrument all the things.
-    attr_reader :instrumenter
-
-    # Internal: Initializes a new adapter instance.
-    #
-    # adapter - Vanilla adapter instance to wrap. Just needs to respond to
-    #           read, write, delete, set_members, set_add, and set_delete.
-    #
-    # options - The Hash of options.
-    #           :local_cache - Where to store the local cache data (default: {}).
-    #                          Must respond to fetch(key, block), delete(key)
-    #                          and clear.
-    #           :instrumenter - What to use to instrument all the things.
-    #
-    def initialize(adapter, options = {})
-      @adapter = adapter
-      @name = adapter.class.name.split('::').last.downcase.to_sym
-      @local_cache = options[:local_cache] || {}
-      @instrumenter = options.fetch(:instrumenter, Flipper::Instrumenters::Noop)
-    end
-
-    # Public: Turns local caching on/off.
-    #
-    # value - The Boolean that decides if local caching is on.
-    def use_local_cache=(value)
-      local_cache.clear
-      @use_local_cache = value
-    end
-
-    # Public: Returns true for using local cache, false for not.
-    def using_local_cache?
-      @use_local_cache == true
-    end
-
-    # Public: Reads a key.
-    def read(key)
-      perform_read(:read, key)
-    end
-
-    # Public: Set a key to a value.
-    def write(key, value)
-      perform_update(:write, key, value.to_s)
-    end
-
-    # Public: Deletes a key.
-    def delete(key)
-      perform_delete(:delete, key)
-    end
-
-    # Public: Returns the members of a set.
-    def set_members(key)
-      perform_read(:set_members, key)
-    end
-
-    # Public: Adds a value to a set.
-    def set_add(key, value)
-      perform_update(:set_add, key, value.to_s)
-    end
-
-    # Public: Deletes a value from a set.
-    def set_delete(key, value)
-      perform_update(:set_delete, key, value.to_s)
-    end
-
-    # Public: Determines equality for an adapter instance when compared to
-    # another object.
-    def eql?(other)
-      self.class.eql?(other.class) && adapter == other.adapter
-    end
-    alias_method :==, :eql?
-
-    # Public: Returns all the features that the adapter knows of.
-    def features
-      set_members(FeaturesKey)
-    end
-
-    # Internal: Adds a known feature to the set of features.
-    def feature_add(name)
-      set_add(FeaturesKey, name.to_s)
-    end
-
-    # Public: Pretty string version for debugging.
-    def inspect
-      attributes = [
-        "name=#{name.inspect}",
-        "use_local_cache=#{@use_local_cache.inspect}"
-      ]
-      "#<#{self.class.name}:#{object_id} #{attributes.join(', ')}>"
-    end
-
-    # Private
-    def perform_read(operation, key)
-      if using_local_cache?
-        local_cache.fetch(key.to_s) {
-          local_cache[key.to_s] = @adapter.send(operation, key)
-        }
-      else
-        payload = {
-          :key => key,
-          :operation => operation,
-          :adapter_name => @name,
-        }
-
-        @instrumenter.instrument(InstrumentationName, payload) { |payload|
-          payload[:result] = @adapter.send(operation, key)
-        }
-      end
-    end
-
-    # Private
-    def perform_update(operation, key, value)
-      payload = {
-        :key => key,
-        :value => value,
-        :operation => operation,
-        :adapter_name => @name,
-      }
-
-      result = @instrumenter.instrument(InstrumentationName, payload) { |payload|
-        payload[:result] = @adapter.send(operation, key, value)
-      }
-
-      if using_local_cache?
-        local_cache.delete(key.to_s)
-      end
-
-      result
-    end
-
-    # Private
-    def perform_delete(operation, key)
-      payload = {
-        :key => key,
-        :operation => operation,
-        :adapter_name => @name,
-      }
-
-      result = @instrumenter.instrument(InstrumentationName, payload) { |payload|
-        payload[:result] = @adapter.send(operation, key)
-      }
-
-      if using_local_cache?
-        local_cache.delete(key.to_s)
-      end
-
-      result
-    end
+  module Adapter
+    # adding a module include so we have some hooks for stuff down the road
   end
 end

data/lib/flipper/adapters/decorator.rb

@@ -0,0 +1,9 @@
+require 'flipper/decorator'
+
+module Flipper
+  module Adapters
+    class Decorator < ::Flipper::Decorator
+      include Flipper::Adapter
+    end
+  end
+end

data/lib/flipper/adapters/instrumented.rb

@@ -0,0 +1,92 @@
+require 'flipper/adapters/decorator'
+require 'flipper/instrumenters/noop'
+
+module Flipper
+  module Adapters
+    class Instrumented < Decorator
+      # Private: The name of instrumentation events.
+      InstrumentationName = "adapter_operation.#{InstrumentationNamespace}"
+
+      # Private: What is used to instrument all the things.
+      attr_reader :instrumenter
+
+      # Internal: Initializes a new adapter instance.
+      #
+      # adapter - Vanilla adapter instance to wrap.
+      #
+      # options - The Hash of options.
+      #           :instrumenter - What to use to instrument all the things.
+      #
+      def initialize(adapter, options = {})
+        super(adapter)
+        @name = :instrumented
+        @instrumenter = options.fetch(:instrumenter, Flipper::Instrumenters::Noop)
+      end
+
+      def get(feature)
+        payload = {
+          :operation => :get,
+          :adapter_name => name,
+          :feature_name => feature.name,
+        }
+
+        @instrumenter.instrument(InstrumentationName, payload) { |payload|
+          payload[:result] = super
+        }
+      end
+
+      # Public: Enable feature gate for thing.
+      def enable(feature, gate, thing)
+        payload = {
+          :operation => :enable,
+          :adapter_name => name,
+          :feature_name => feature.name,
+          :gate_name => gate.name,
+        }
+
+        @instrumenter.instrument(InstrumentationName, payload) { |payload|
+          payload[:result] = super
+        }
+      end
+
+      # Public: Disable feature gate for thing.
+      def disable(feature, gate, thing)
+        payload = {
+          :operation => :disable,
+          :adapter_name => name,
+          :feature_name => feature.name,
+          :gate_name => gate.name,
+        }
+
+        @instrumenter.instrument(InstrumentationName, payload) { |payload|
+          payload[:result] = super
+        }
+      end
+
+      # Public: Returns all the features that the adapter knows of.
+      def features
+        payload = {
+          :operation => :features,
+          :adapter_name => name,
+        }
+
+        @instrumenter.instrument(InstrumentationName, payload) { |payload|
+          payload[:result] = super
+        }
+      end
+
+      # Internal: Adds a known feature to the set of features.
+      def add(feature)
+        payload = {
+          :operation => :add,
+          :adapter_name => name,
+          :feature_name => feature.name,
+        }
+
+        @instrumenter.instrument(InstrumentationName, payload) { |payload|
+          payload[:result] = super
+        }
+      end
+    end
+  end
+end