flipper 0.5.0 → 0.6.0

data/README.md

@@ -1,4 +1,4 @@
-# Flipper
+![flipper logo](https://raw.github.com/jnunemaker/flipper-ui/master/lib/flipper/ui/public/flipper/images/logo.png)
 
 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.
 
@@ -167,13 +167,49 @@ Randomness is not a good idea for enabling new features in the UI. Most of the t
 
 ## Adapters
 
-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.
+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 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)
 
+The basic API for an adapter is this:
+
+* `features` - Get the set of known features.
+* `add(feature)` - Add a feature to the set of known features.
+* `remove(feature)` - Remove a feature from the set of known features.
+* `clear(feature)` - Clear all gate values for a feature.
+* `get(feature)` - Get all gate values for a feature.
+* `enable(feature, gate, thing)` - Enable a gate for a thing.
+* `disable(feature, gate, thing)` - Disable a gate for a thing.
+
+If you would like to make your own adapter, there are shared adapter specs that you can use to verify that you have everything working correctly.
+
+For example, here is what the in-memory adapter spec looks like:
+
+```ruby
+require 'helper'
+require 'flipper/adapters/memory'
+
+# The shared specs are included with the flipper gem so you can use them in
+# separate adapter specific gems.
+require 'flipper/spec/shared_adapter_specs'
+
+describe Flipper::Adapters::Memory do
+
+  # an instance of the new adapter you are trying to create
+  subject { described_class.new }
+
+  # include the shared specs that the subject must pass
+  it_should_behave_like 'a flipper adapter'
+end
+```
+
+A good place to start when creating your own adapter is to copy one of the adapters mentioned above and replace the client specific code with whatever client you are attempting to adapt.
+
+I would also recommend setting `fail_fast = true` in your RSpec configuration as that will just give you one failure at a time to work through. It is also handy to have the shared adapter spec file open.
+
 ## Optimization
 
 One optimization that flipper provides is a memoizing middleware. The memoizing middleware ensures that you only make one adapter call per feature per request.
@@ -183,13 +219,21 @@ This means if you check the same feature over and over, it will only make one mo
 You can use the middleware from a Rails initializer like so:
 
 ```ruby
+# create flipper dsl instance, see above Usage for more details
+flipper = Flipper.new(...)
+
 require 'flipper/middleware/memoizer'
+config.middleware.use Flipper::Middleware::Memoizer, flipper
+```
 
-# create flipper dsl instance, see above examples for more details
-flipper = Flipper.new(...)
+If you set your flipper instance up in an initializer, you can pass a block to the middleware and it will lazily load the instance the first time the middleware is invoked.
+
+```ruby
+# config/initializers/flipper.rb
+$flipper = Flipper.new(...)
 
-# add the middleware
-Rails.application.config.middleware.use Flipper::Middleware::Memoizer, flipper
+# config/application.rb
+config.middleware.use Flipper::Middleware::Memoizer, lambda { $flipper }
 ```
 
 **Note**: Be sure that the middlware is high enough up in your stack that all feature checks are wrapped.

data/lib/flipper/adapters/instrumented.rb

@@ -23,9 +23,22 @@ module Flipper
         @instrumenter = options.fetch(:instrumenter, Flipper::Instrumenters::Noop)
       end
 
-      def get(feature)
+      # Public
+      def features
         payload = {
-          :operation => :get,
+          :operation => :features,
+          :adapter_name => name,
+        }
+
+        @instrumenter.instrument(InstrumentationName, payload) { |payload|
+          payload[:result] = super
+        }
+      end
+
+      # Public
+      def add(feature)
+        payload = {
+          :operation => :add,
           :adapter_name => name,
           :feature_name => feature.name,
         }
@@ -35,13 +48,12 @@ module Flipper
         }
       end
 
-      # Public: Enable feature gate for thing.
-      def enable(feature, gate, thing)
+      # Public
+      def remove(feature)
         payload = {
-          :operation => :enable,
+          :operation => :remove,
           :adapter_name => name,
           :feature_name => feature.name,
-          :gate_name => gate.name,
         }
 
         @instrumenter.instrument(InstrumentationName, payload) { |payload|
@@ -49,13 +61,12 @@ module Flipper
         }
       end
 
-      # Public: Disable feature gate for thing.
-      def disable(feature, gate, thing)
+      # Public
+      def clear(feature)
         payload = {
-          :operation => :disable,
+          :operation => :clear,
           :adapter_name => name,
           :feature_name => feature.name,
-          :gate_name => gate.name,
         }
 
         @instrumenter.instrument(InstrumentationName, payload) { |payload|
@@ -63,11 +74,12 @@ module Flipper
         }
       end
 
-      # Public: Returns all the features that the adapter knows of.
-      def features
+      # Public
+      def get(feature)
         payload = {
-          :operation => :features,
+          :operation => :get,
           :adapter_name => name,
+          :feature_name => feature.name,
         }
 
         @instrumenter.instrument(InstrumentationName, payload) { |payload|
@@ -75,12 +87,27 @@ module Flipper
         }
       end
 
-      # Internal: Adds a known feature to the set of features.
-      def add(feature)
+      # Public
+      def enable(feature, gate, thing)
         payload = {
-          :operation => :add,
+          :operation => :enable,
+          :adapter_name => name,
+          :feature_name => feature.name,
+          :gate_name => gate.name,
+        }
+
+        @instrumenter.instrument(InstrumentationName, payload) { |payload|
+          payload[:result] = super
+        }
+      end
+
+      # Public
+      def disable(feature, gate, thing)
+        payload = {
+          :operation => :disable,
           :adapter_name => name,
           :feature_name => feature.name,
+          :gate_name => gate.name,
         }
 
         @instrumenter.instrument(InstrumentationName, payload) { |payload|

data/lib/flipper/adapters/memoizable.rb

@@ -27,43 +27,60 @@ module Flipper
       end
 
       # Public
-      def get(feature)
+      def features
         if memoizing?
-          cache.fetch(feature) { cache[feature] = super }
+          cache.fetch(FeaturesKey) {
+            cache[FeaturesKey] = super
+          }
         else
           super
         end
       end
 
       # Public
-      def enable(feature, gate, thing)
+      def add(feature)
         result = super
-        cache.delete(feature) if memoizing?
+        cache.delete(FeaturesKey) if memoizing?
         result
       end
 
       # Public
-      def disable(feature, gate, thing)
+      def remove(feature)
+        result = super
+        if memoizing?
+          cache.delete(FeaturesKey)
+          cache.delete(feature)
+        end
+        result
+      end
+
+      # Public
+      def clear(feature)
         result = super
         cache.delete(feature) if memoizing?
         result
       end
 
       # Public
-      def features
+      def get(feature)
         if memoizing?
-          cache.fetch(FeaturesKey) {
-            cache[FeaturesKey] = super
-          }
+          cache.fetch(feature) { cache[feature] = super }
         else
           super
         end
       end
 
       # Public
-      def add(feature)
+      def enable(feature, gate, thing)
         result = super
-        cache.delete(FeaturesKey) if memoizing?
+        cache.delete(feature) if memoizing?
+        result
+      end
+
+      # Public
+      def disable(feature, gate, thing)
+        result = super
+        cache.delete(feature) if memoizing?
         result
       end
 

data/lib/flipper/adapters/memory.rb

@@ -16,6 +16,32 @@ module Flipper
         @name = :memory
       end
 
+      # Public: The set of known features.
+      def features
+        set_members(FeaturesKey)
+      end
+
+      # Public: Adds a feature to the set of known features.
+      def add(feature)
+        features.add(feature.name.to_s)
+        true
+      end
+
+      # Public: Removes a feature from the set of known features and clears
+      # all the values for the feature.
+      def remove(feature)
+        features.delete(feature.name.to_s)
+        clear(feature)
+        true
+      end
+
+      # Public: Clears all the gate values for a feature.
+      def clear(feature)
+        feature.gates.each do |gate|
+          delete key(feature, gate)
+        end
+      end
+
       # Public
       def get(feature)
         result = {}
@@ -52,9 +78,7 @@ module Flipper
       def disable(feature, gate, thing)
         case gate.data_type
         when :boolean
-          feature.gates.each do |gate|
-            delete key(feature, gate)
-          end
+          clear(feature)
         when :integer
           write key(feature, gate), thing.value.to_s
         when :set
@@ -66,18 +90,7 @@ module Flipper
         true
       end
 
-      # Public: Adds a feature to the set of known features.
-      def add(feature)
-        features.add(feature.name.to_s)
-
-        true
-      end
-
-      # Public: The set of known features.
-      def features
-        set_members(FeaturesKey)
-      end
-
+      # Public
       def inspect
         attributes = [
           "name=:memory",
@@ -86,7 +99,7 @@ module Flipper
         "#<#{self.class.name}:#{object_id} #{attributes.join(', ')}>"
       end
 
-      # private
+      # Private
       def key(feature, gate)
         "#{feature.key}/#{gate.key}"
       end

data/lib/flipper/adapters/operation_logger.rb

@@ -9,11 +9,13 @@ module Flipper
       Operation = Struct.new(:type, :args)
 
       OperationTypes = [
-        :get,
+        :features,
         :add,
+        :remove,
+        :clear,
+        :get,
         :enable,
         :disable,
-        :features
       ]
 
       # Internal: An array of the operations that have happened.
@@ -25,6 +27,7 @@ module Flipper
         @operations = operations || []
       end
 
+      # Wraps original method with in memory log of operations performed.
       OperationTypes.each do |type|
         class_eval <<-EOE
           def #{type}(*args)
@@ -36,9 +39,7 @@ module Flipper
 
       # Public: Count the number of times a certain operation happened.
       def count(type)
-        @operations.select { |operation|
-          operation.type == type
-        }.size
+        @operations.select { |operation| operation.type == type }.size
       end
 
       # Public: Resets the operation log to empty

data/lib/flipper/feature.rb

@@ -59,7 +59,11 @@ module Flipper
         gate = gate_for(thing)
         payload[:gate_name] = gate.name
 
-        adapter.disable self, gate, gate.wrap(thing)
+        if gate.is_a?(Gates::Boolean)
+          adapter.clear self
+        else
+          adapter.disable self, gate, gate.wrap(thing)
+        end
       }
     end
 

data/lib/flipper/middleware/memoizer.rb

@@ -3,18 +3,43 @@ require 'rack/body_proxy'
 module Flipper
   module Middleware
     class Memoizer
-      def initialize(app, flipper)
+      # Public: Initializes an instance of the UI middleware.
+      #
+      # app - The app this middleware is included in.
+      # flipper_or_block - The Flipper::DSL instance or a block that yields a
+      #                    Flipper::DSL instance to use for all operations.
+      #
+      # Examples
+      #
+      #   flipper = Flipper.new(...)
+      #
+      #   # using with a normal flipper instance
+      #   use Flipper::Middleware::Memoizer, flipper
+      #
+      #   # using with a block that yields a flipper instance
+      #   use Flipper::Middleware::Memoizer, lambda { Flipper.new(...) }
+      #
+      def initialize(app, flipper_or_block)
         @app = app
-        @flipper = flipper
+
+        if flipper_or_block.respond_to?(:call)
+          @flipper_block = flipper_or_block
+        else
+          @flipper = flipper_or_block
+        end
+      end
+
+      def flipper
+        @flipper ||= @flipper_block.call
       end
 
       def call(env)
-        original = @flipper.adapter.memoizing?
-        @flipper.adapter.memoize = true
+        original = flipper.adapter.memoizing?
+        flipper.adapter.memoize = true
 
         response = @app.call(env)
         response[2] = Rack::BodyProxy.new(response[2]) {
-          @flipper.adapter.memoize = original
+          flipper.adapter.memoize = original
         }
         response
       end

data/lib/flipper/spec/shared_adapter_specs.rb

@@ -161,7 +161,7 @@ shared_examples_for 'a flipper adapter' do
     result[:percentage_of_actors].should eq('10')
   end
 
-  it "can add and list known features" do
+  it "can add, remove and list known features" do
     subject.features.should eq(Set.new)
 
     subject.add(flipper[:stats]).should be_true
@@ -169,5 +169,53 @@ shared_examples_for 'a flipper adapter' do
 
     subject.add(flipper[:search]).should be_true
     subject.features.should eq(Set['stats', 'search'])
+
+    subject.remove(flipper[:stats]).should be_true
+    subject.features.should eq(Set['search'])
+
+    subject.remove(flipper[:search]).should be_true
+    subject.features.should eq(Set.new)
+  end
+
+  it "clears all the gate values for the feature on remove" do
+    actor_22 = actor_class.new('22')
+    subject.enable(feature, boolean_gate, flipper.boolean).should be_true
+    subject.enable(feature, group_gate, flipper.group(:admins)).should be_true
+    subject.enable(feature, actor_gate, flipper.actor(actor_22)).should be_true
+    subject.enable(feature, actors_gate, flipper.actors(25)).should be_true
+    subject.enable(feature, random_gate, flipper.random(45)).should be_true
+
+    subject.remove(feature).should be_true
+
+    subject.get(feature).should eq({
+      :boolean => nil,
+      :groups => Set.new,
+      :actors => Set.new,
+      :percentage_of_actors => nil,
+      :percentage_of_random => nil,
+    })
+  end
+
+  it "can clear all the gate values for a feature" do
+    actor_22 = actor_class.new('22')
+    subject.enable(feature, boolean_gate, flipper.boolean).should be_true
+    subject.enable(feature, group_gate, flipper.group(:admins)).should be_true
+    subject.enable(feature, actor_gate, flipper.actor(actor_22)).should be_true
+    subject.enable(feature, actors_gate, flipper.actors(25)).should be_true
+    subject.enable(feature, random_gate, flipper.random(45)).should be_true
+
+    subject.clear(feature).should be_true
+
+    subject.get(feature).should eq({
+      :boolean => nil,
+      :groups => Set.new,
+      :actors => Set.new,
+      :percentage_of_actors => nil,
+      :percentage_of_random => nil,
+    })
+  end
+
+  it "does not complain clearing a feature that does not exist in adapter" do
+    subject.clear(flipper[:stats]).should be_true
   end
 end

data/lib/flipper/version.rb

@@ -1,3 +1,3 @@
 module Flipper
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/spec/flipper/adapters/instrumented_spec.rb

@@ -77,6 +77,34 @@ describe Flipper::Adapters::Instrumented do
     end
   end
 
+  describe "#remove" do
+    it "records instrumentation" do
+      result = subject.remove(feature)
+
+      event = instrumenter.events.last
+      event.should_not be_nil
+      event.name.should eq('adapter_operation.flipper')
+      event.payload[:operation].should eq(:remove)
+      event.payload[:adapter_name].should eq(:memory)
+      event.payload[:feature_name].should eq(:stats)
+      event.payload[:result].should be(result)
+    end
+  end
+
+  describe "#clear" do
+    it "records instrumentation" do
+      result = subject.clear(feature)
+
+      event = instrumenter.events.last
+      event.should_not be_nil
+      event.name.should eq('adapter_operation.flipper')
+      event.payload[:operation].should eq(:clear)
+      event.payload[:adapter_name].should eq(:memory)
+      event.payload[:feature_name].should eq(:stats)
+      event.payload[:result].should be(result)
+    end
+  end
+
   describe "#features" do
     it "records instrumentation" do
       result = subject.features

data/spec/flipper/adapters/memoizable_spec.rb

@@ -164,7 +164,7 @@ describe Flipper::Adapters::Memoizable do
         subject.memoize = true
       end
 
-      it "unmemoizes features" do
+      it "unmemoizes the known features" do
         cache[features_key] = {:some => 'thing'}
         subject.add(flipper[:stats])
         cache.should be_empty
@@ -181,4 +181,61 @@ describe Flipper::Adapters::Memoizable do
       end
     end
   end
+
+  describe "#remove" do
+    context "with memoization enabled" do
+      before do
+        subject.memoize = true
+      end
+
+      it "unmemoizes the known features" do
+        cache[features_key] = {:some => 'thing'}
+        subject.remove(flipper[:stats])
+        cache.should be_empty
+      end
+
+      it "unmemoizes the feature" do
+        feature = flipper[:stats]
+        cache[feature] = {:some => 'thing'}
+        subject.remove(feature)
+        cache[feature].should be_nil
+      end
+    end
+
+    context "with memoization disabled" do
+      before do
+        subject.memoize = false
+      end
+
+      it "returns result" do
+        subject.remove(flipper[:stats]).should eq(adapter.remove(flipper[:stats]))
+      end
+    end
+  end
+
+  describe "#clear" do
+    context "with memoization enabled" do
+      before do
+        subject.memoize = true
+      end
+
+      it "unmemoizes feature" do
+        feature = flipper[:stats]
+        cache[feature] = {:some => 'thing'}
+        subject.clear(feature)
+        cache[feature].should be_nil
+      end
+    end
+
+    context "with memoization disabled" do
+      before do
+        subject.memoize = false
+      end
+
+      it "returns result" do
+        feature = flipper[:stats]
+        subject.clear(feature).should eq(adapter.clear(feature))
+      end
+    end
+  end
 end

data/spec/flipper/middleware/memoizer_spec.rb

@@ -9,93 +9,123 @@ describe Flipper::Middleware::Memoizer do
 
   let(:source)         { {} }
   let(:memory_adapter) { Flipper::Adapters::Memory.new(source) }
-  let(:adapter)        { Flipper::Adapters::OperationLogger.new(memory_adapter) }
-  let(:flipper)        { Flipper.new(adapter) }
-
-  let(:app) {
-    # ensure scoped for builder block, annoying...
-    instance = flipper
-    middleware = described_class
-
-    Rack::Builder.new do
-      use middleware, instance
-
-      map "/" do
-        run lambda {|env| [200, {}, []] }
-      end
-
-      map "/fail" do
-        run lambda {|env| raise "FAIL!" }
-      end
-    end.to_app
+  let(:adapter)        {
+    Flipper::Adapters::OperationLogger.new(memory_adapter)
   }
+  let(:flipper)        { Flipper.new(adapter) }
 
   after do
     flipper.adapter.memoize = nil
   end
 
-  it "delegates" do
-    called = false
-    app = lambda { |env|
-      called = true
-      [200, {}, nil]
-    }
-    middleware = described_class.new app, flipper
-    middleware.call({})
-    called.should be_true
+  shared_examples_for "flipper middleware" do
+    it "delegates" do
+      called = false
+      app = lambda { |env|
+        called = true
+        [200, {}, nil]
+      }
+      middleware = described_class.new app, flipper
+      middleware.call({})
+      called.should be_true
+    end
+
+    it "disables local cache after body close" do
+      app = lambda { |env| [200, {}, []] }
+      middleware = described_class.new app, flipper
+      body = middleware.call({}).last
+
+      flipper.adapter.memoizing?.should be_true
+      body.close
+      flipper.adapter.memoizing?.should be_false
+    end
+
+    it "clears local cache after body close" do
+      app = lambda { |env| [200, {}, []] }
+      middleware = described_class.new app, flipper
+      body = middleware.call({}).last
+
+      flipper.adapter.cache['hello'] = 'world'
+      body.close
+      flipper.adapter.cache.should be_empty
+    end
+
+    it "clears the local cache with a successful request" do
+      flipper.adapter.cache['hello'] = 'world'
+      get '/'
+      flipper.adapter.cache.should be_empty
+    end
+
+    it "clears the local cache even when the request raises an error" do
+      flipper.adapter.cache['hello'] = 'world'
+      get '/fail' rescue nil
+      flipper.adapter.cache.should be_empty
+    end
+
+    it "caches getting a feature for duration of request" do
+      flipper[:stats].enable
+
+      # clear the log of operations
+      adapter.reset
+
+      app = lambda { |env|
+        flipper[:stats].enabled?
+        flipper[:stats].enabled?
+        flipper[:stats].enabled?
+        flipper[:stats].enabled?
+        flipper[:stats].enabled?
+        flipper[:stats].enabled?
+        [200, {}, []]
+      }
+
+      middleware = described_class.new app, flipper
+      middleware.call({})
+
+      adapter.count(:get).should be(1)
+    end
   end
 
-  it "disables local cache after body close" do
-    app = lambda { |env| [200, {}, []] }
-    middleware = described_class.new app, flipper
-    body = middleware.call({}).last
+  context "with flipper instance" do
+    let(:app) {
+      # ensure scoped for builder block, annoying...
+      instance = flipper
+      middleware = described_class
 
-    flipper.adapter.memoizing?.should be_true
-    body.close
-    flipper.adapter.memoizing?.should be_false
-  end
+      Rack::Builder.new do
+        use middleware, instance
 
-  it "clears local cache after body close" do
-    app = lambda { |env| [200, {}, []] }
-    middleware = described_class.new app, flipper
-    body = middleware.call({}).last
+        map "/" do
+          run lambda {|env| [200, {}, []] }
+        end
 
-    flipper.adapter.cache['hello'] = 'world'
-    body.close
-    flipper.adapter.cache.should be_empty
-  end
+        map "/fail" do
+          run lambda {|env| raise "FAIL!" }
+        end
+      end.to_app
+    }
 
-  it "clears the local cache with a successful request" do
-    flipper.adapter.cache['hello'] = 'world'
-    get '/'
-    flipper.adapter.cache.should be_empty
+    include_examples "flipper middleware"
   end
 
-  it "clears the local cache even when the request raises an error" do
-    flipper.adapter.cache['hello'] = 'world'
-    get '/fail' rescue nil
-    flipper.adapter.cache.should be_empty
-  end
+  context "with block that yields flipper instance" do
+    let(:app) {
+      # ensure scoped for builder block, annoying...
+      instance = flipper
+      middleware = described_class
 
-  it "caches getting a feature for duration of request" do
-    flipper[:stats].enable
+      Rack::Builder.new do
+        use middleware, lambda { instance }
 
-    # clear the log of operations
-    adapter.reset
+        map "/" do
+          run lambda {|env| [200, {}, []] }
+        end
 
-    app = lambda { |env|
-      flipper[:stats].enabled?
-      flipper[:stats].enabled?
-      flipper[:stats].enabled?
-      flipper[:stats].enabled?
-      flipper[:stats].enabled?
-      flipper[:stats].enabled?
-      [200, {}, []]
+        map "/fail" do
+          run lambda {|env| raise "FAIL!" }
+        end
+      end.to_app
     }
 
-    middleware = described_class.new app, flipper
-    middleware.call({})
-
-    adapter.count(:get).should be(1)
+    include_examples "flipper middleware"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flipper
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-16 00:00:00.000000000 Z
+date: 2013-02-20 00:00:00.000000000 Z
 dependencies: []
 description: Feature flipper for any adapter
 email:
@@ -110,7 +110,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4560839249202297958
+      hash: 592688489057647185
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -119,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4560839249202297958
+      hash: 592688489057647185
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23