flipper 0.3.0 → 0.4.0

data/lib/flipper/gates/percentage_of_actors.rb

@@ -3,25 +3,44 @@ require 'zlib'
 module Flipper
   module Gates
     class PercentageOfActors < Gate
-      Key = :perc_actors
+      # Internal: The name of the gate. Used for instrumentation, etc.
+      def name
+        :percentage_of_actors
+      end
 
-      def type_key
-        Key
+      # Internal: The piece of the adapter key that is unique to the gate class.
+      def key
+        :perc_actors
       end
 
-      def open?(actor)
-        percentage = toggle.value
+      # Internal: Checks if the gate is open for a thing.
+      #
+      # Returns true if gate open for thing, false if not.
+      def open?(thing)
+        instrument(:open?, thing) { |payload|
+          percentage = toggle.value.to_i
 
-        if percentage.nil?
-          false
-        else
-          Zlib.crc32(actor.identifier.to_s) % 100 < percentage
-        end
+          if Types::Actor.wrappable?(thing)
+            actor = Types::Actor.wrap(thing)
+            key = "#{@feature.name}#{actor.value}"
+            Zlib.crc32(key) % 100 < percentage
+          else
+            false
+          end
+        }
       end
 
       def protects?(thing)
         thing.is_a?(Flipper::Types::PercentageOfActors)
       end
+
+      def description
+        if enabled?
+          "#{toggle.value}% of actors"
+        else
+          'disabled'
+        end
+      end
     end
   end
 end

data/lib/flipper/gates/percentage_of_random.rb

@@ -1,25 +1,38 @@
 module Flipper
   module Gates
     class PercentageOfRandom < Gate
-      Key = :perc_time
+      # Internal: The name of the gate. Used for instrumentation, etc.
+      def name
+        :percentage_of_random
+      end
 
-      def type_key
-        Key
+      # Internal: The piece of the adapter key that is unique to the gate class.
+      def key
+        :perc_time
       end
 
-      def open?(actor)
-        percentage = toggle.value
+      # Internal: Checks if the gate is open for a thing.
+      #
+      # Returns true if gate open for thing, false if not.
+      def open?(thing)
+        instrument(:open?, thing) { |payload|
+          percentage = toggle.value.to_i
 
-        if percentage.nil?
-          false
-        else
           rand < (percentage / 100.0)
-        end
+        }
       end
 
       def protects?(thing)
         thing.is_a?(Flipper::Types::PercentageOfRandom)
       end
+
+      def description
+        if enabled?
+          "#{toggle.value}% of the time"
+        else
+          'disabled'
+        end
+      end
     end
   end
 end

data/lib/flipper/instrumentation/log_subscriber.rb

@@ -0,0 +1,107 @@
+require 'securerandom'
+require 'active_support/notifications'
+require 'active_support/log_subscriber'
+
+module Flipper
+  module Instrumentation
+    class LogSubscriber < ::ActiveSupport::LogSubscriber
+      # Logs a feature operation.
+      #
+      # Example Output
+      #
+      #   flipper[:search].enabled?(user)
+      #   # Flipper feature(search) enabled? false (1.2ms)  [ thing=#<struct flipper_id="1"> ]
+      #
+      # Returns nothing.
+      def feature_operation(event)
+        return unless logger.debug?
+
+        feature_name = event.payload[:feature_name]
+        gate_name = event.payload[:gate_name]
+        operation = event.payload[:operation]
+        result = event.payload[:result]
+        thing = event.payload[:thing]
+
+        description = "Flipper feature(#{feature_name}) #{operation} #{result.inspect}"
+        details = "thing=#{thing.inspect}"
+
+        unless gate_name.nil?
+          details += " gate_name=#{gate_name}"
+        end
+
+        name = '%s (%.1fms)' % [description, event.duration]
+        debug "  #{color(name, CYAN, true)}  [ #{details} ]"
+      end
+
+      # Logs an adapter operation. If operation is for a feature, then that
+      # feature is included in log output.
+      #
+      # Example Output
+      #
+      #   # log output for adapter operation with feature
+      #   # Flipper feature(search) adapter(memory) set_add("search/actors") (0.0ms)  [ result=#<Set: {"1"}> value="1" ]
+      #
+      #   # log output for adapter operation with no feature
+      #   # Flipper adapter(memory) set_add("features") (0.0ms)  [ result=#<Set: {"search"}> value="search" ]
+      #
+      # Returns nothing.
+      def adapter_operation(event)
+        return unless logger.debug?
+
+        adapter_name = event.payload[:adapter_name]
+        operation = event.payload[:operation]
+        result = event.payload[:result]
+        value = event.payload[:value]
+        key = event.payload[:key]
+
+        feature_description = if key.respond_to?(:feature_name)
+          "Flipper feature(#{key.feature_name})"
+        else
+          "Flipper"
+        end
+
+        adapter_description = "adapter(#{adapter_name})"
+        operation_description = "#{operation}(#{key.to_s.inspect})"
+        description = "#{feature_description} #{adapter_description} #{operation_description}"
+        details = "result=#{result.inspect}"
+
+        if event.payload.key?(:value)
+          details += " value=#{value.inspect}"
+        end
+
+        name = '%s (%.1fms)' % [description, event.duration]
+        debug "  #{color(name, CYAN, true)}  [ #{details} ]"
+      end
+
+      # Logs a gate operation.
+      #
+      # Example Output
+      #
+      #   flipper[:search].enabled?(user)
+      #   # Flipper feature(search) gate(boolean) open false (0.1ms)  [ thing=#<struct flipper_id="1"> ]
+      #   # Flipper feature(search) gate(group) open false (0.1ms)  [ thing=#<struct flipper_id="1"> ]
+      #   # Flipper feature(search) gate(actor) open false (0.1ms)  [ thing=#<struct flipper_id="1"> ]
+      #   # Flipper feature(search) gate(percentage_of_actors) open false (0.1ms)  [ thing=#<struct flipper_id="1"> ]
+      #   # Flipper feature(search) gate(percentage_of_random) open false (0.1ms)  [ thing=#<struct flipper_id="1"> ]
+      #
+      # Returns nothing.
+      def gate_operation(event)
+        return unless logger.debug?
+
+        feature_name = event.payload[:feature_name]
+        gate_name = event.payload[:gate_name]
+        operation = event.payload[:operation]
+        result = event.payload[:result]
+        thing = event.payload[:thing]
+
+        description = "Flipper feature(#{feature_name}) gate(#{gate_name}) #{operation} #{result.inspect}"
+        details = "thing=#{thing.inspect}"
+
+        name = '%s (%.1fms)' % [description, event.duration]
+        debug "  #{color(name, CYAN, true)}  [ #{details} ]"
+      end
+    end
+  end
+
+  Instrumentation::LogSubscriber.attach_to InstrumentationNamespace
+end

data/lib/flipper/instrumentation/metriks.rb

@@ -0,0 +1,6 @@
+require 'securerandom'
+require 'active_support/notifications'
+require 'flipper/instrumentation/metriks_subscriber'
+
+ActiveSupport::Notifications.subscribe /\.flipper$/,
+  Flipper::Instrumentation::MetriksSubscriber

data/lib/flipper/instrumentation/metriks_subscriber.rb

@@ -0,0 +1,92 @@
+# Note: You should never need to require this file directly if you are using
+# ActiveSupport::Notifications. Instead, you should require the metriks file
+# that lives in the same directory as this file. The benefit is that it
+# subscribes to the correct events and does everything for your.
+require 'metriks'
+
+module Flipper
+  module Instrumentation
+    class MetriksSubscriber
+      # Public: Use this as the subscribed block.
+      def self.call(name, start, ending, transaction_id, payload)
+        new(name, start, ending, transaction_id, payload).update
+      end
+
+      # Private: Initializes a new event processing instance.
+      def initialize(name, start, ending, transaction_id, payload)
+        @name = name
+        @start = start
+        @ending = ending
+        @payload = payload
+        @duration = ending - start
+        @transaction_id = transaction_id
+      end
+
+      def update
+        operation_type = @name.split('.').first
+        method_name = "update_#{operation_type}_metrics"
+
+        if respond_to?(method_name)
+          send(method_name)
+        else
+          puts "Could not update #{operation_type} metrics as MetriksSubscriber did not respond to `#{method_name}`"
+        end
+      end
+
+      def update_feature_operation_metrics
+        feature_name = @payload[:feature_name]
+        gate_name = @payload[:gate_name]
+        operation = strip_trailing_question_mark(@payload[:operation])
+        result = @payload[:result]
+        thing = @payload[:thing]
+
+        Metriks.timer("flipper.feature_operation.#{operation}").update(@duration)
+
+        if @payload[:operation] == :enabled?
+          metric_name = if result
+            "flipper.feature.#{feature_name}.enabled"
+          else
+            "flipper.feature.#{feature_name}.disabled"
+          end
+
+          Metriks.meter(metric_name).mark
+        end
+      end
+
+      def update_adapter_operation_metrics
+        adapter_name = @payload[:adapter_name]
+        operation = @payload[:operation]
+        result = @payload[:result]
+        value = @payload[:value]
+        key = @payload[:key]
+
+        Metriks.timer("flipper.adapter.#{adapter_name}.#{operation}").update(@duration)
+      end
+
+      def update_gate_operation_metrics
+        feature_name = @payload[:feature_name]
+        gate_name = @payload[:gate_name]
+        operation = strip_trailing_question_mark(@payload[:operation])
+        result = @payload[:result]
+        thing = @payload[:thing]
+
+        Metriks.timer("flipper.gate_operation.#{gate_name}.#{operation}").update(@duration)
+        Metriks.timer("flipper.feature.#{feature_name}.gate_operation.#{gate_name}.#{operation}").update(@duration)
+
+        if @payload[:operation] == :open?
+          metric_name = if result
+            "flipper.feature.#{feature_name}.gate.#{gate_name}.open"
+          else
+            "flipper.feature.#{feature_name}.gate.#{gate_name}.closed"
+          end
+
+          Metriks.meter(metric_name).mark
+        end
+      end
+
+      def strip_trailing_question_mark(operation)
+        operation.to_s.gsub(/\?$/, '')
+      end
+    end
+  end
+end

data/lib/flipper/instrumenters/memory.rb

@@ -0,0 +1,25 @@
+module Flipper
+  module Instrumenters
+    # Instrumentor that is useful for tests as it stores each of the events that
+    # are instrumented.
+    class Memory
+      Event = Struct.new(:name, :payload, :result)
+
+      attr_reader :events
+
+      def initialize
+        @events = []
+      end
+
+      def instrument(name, payload = {})
+        result = if block_given?
+          yield payload
+        else
+          nil
+        end
+        @events << Event.new(name, payload, result)
+        result
+      end
+    end
+  end
+end

data/lib/flipper/instrumenters/noop.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Instrumenters
+    class Noop
+      def self.instrument(name, payload = {})
+        yield payload if block_given?
+      end
+    end
+  end
+end

data/lib/flipper/key.rb

@@ -1,19 +1,38 @@
 module Flipper
+  # Private: Used internally in flipper to create key to be used for feature in
+  # the adapter. You should never need to use this.
   class Key
+    # Private
     Separator = '/'
 
-    attr_reader :prefix, :suffix
+    # Private
+    attr_reader :feature_name
 
-    def initialize(prefix, suffix)
-      @prefix, @suffix = prefix, suffix
+    # Private
+    attr_reader :gate_key
+
+    # Internal
+    def initialize(feature_name, gate_key)
+      @feature_name, @gate_key = feature_name, gate_key
     end
 
+    # Private
     def separator
       Separator.dup
     end
 
+    # Private
     def to_s
-      "#{prefix}#{separator}#{suffix}"
+      "#{feature_name}#{separator}#{gate_key}"
+    end
+
+    # Internal: Pretty string version for debugging.
+    def inspect
+      attributes = [
+        "feature_name=#{feature_name.inspect}",
+        "gate_key=#{gate_key.inspect}",
+      ]
+      "#<#{self.class.name}:#{object_id} #{attributes.join(', ')}>"
     end
   end
 end

data/lib/flipper/registry.rb

@@ -1,12 +1,22 @@
 require 'thread'
 
 module Flipper
+  # Internal: Used to store registry of groups by name.
   class Registry
     include Enumerable
 
     class Error < StandardError; end
     class DuplicateKey < Error; end
-    class MissingKey < Error; end
+
+    class KeyNotFound < Error
+      # Public: The key that was not found
+      attr_reader :key
+
+      def initialize(key)
+        @key = key
+        super("Key #{key.inspect} not found")
+      end
+    end
 
     def initialize(source = {})
       @mutex = Mutex.new
@@ -22,19 +32,25 @@ module Flipper
     end
 
     def add(key, value)
-      @mutex.synchronize do
+      key = key.to_sym
+
+      @mutex.synchronize {
         if @source[key]
           raise DuplicateKey, "#{key} is already registered"
         else
           @source[key] = value
         end
-      end
+      }
     end
 
     def get(key)
-      @mutex.synchronize do
-        @source[key]
-      end
+      key = key.to_sym
+
+      @mutex.synchronize {
+        @source.fetch(key) {
+          raise KeyNotFound.new(key)
+        }
+      }
     end
 
     def each(&block)

data/lib/flipper/spec/shared_adapter_specs.rb

@@ -1,5 +1,12 @@
 require 'set'
 
+shared_examples_for 'a working percentage' do
+  it "does not raise when used" do
+    feature.enable percentage
+    expect { feature.enabled?(actor) }.to_not raise_error
+  end
+end
+
 # Requires the following methods
 # subject
 # read_key(key)
@@ -35,24 +42,24 @@ shared_examples_for 'a flipper adapter' do
 
   describe "#set_add" do
     it "adds value to store" do
-      subject.set_add(key, 1)
-      read_key(key).should eq(Set[1])
+      subject.set_add(key, '1')
+      read_key(key).should eq(Set['1'])
     end
 
     it "does not add same value more than once" do
-      subject.set_add(key, 1)
-      subject.set_add(key, 1)
-      subject.set_add(key, 1)
-      subject.set_add(key, 2)
-      read_key(key).should eq(Set[1, 2])
+      subject.set_add(key, '1')
+      subject.set_add(key, '1')
+      subject.set_add(key, '1')
+      subject.set_add(key, '2')
+      read_key(key).should eq(Set['1', '2'])
     end
   end
 
   describe "#set_delete" do
     it "removes value from set if key in store" do
-      write_key key, Set[1, 2]
-      subject.set_delete(key, 1)
-      read_key(key).should eq(Set[2])
+      write_key key, Set['1', '2']
+      subject.set_delete(key, '1')
+      read_key(key).should eq(Set['2'])
     end
 
     it "works fine if key not in store" do
@@ -66,12 +73,52 @@ shared_examples_for 'a flipper adapter' do
     end
 
     it "returns set if in store" do
-      write_key key, Set[1, 2]
-      subject.set_members(key).should eq(Set[1, 2])
+      write_key key, Set['1', '2']
+      subject.set_members(key).should eq(Set['1', '2'])
     end
   end
 
   it "should work with Flipper.new" do
     Flipper.new(subject).should_not be_nil
   end
+
+  context "working with values" do
+    it "always uses strings" do
+      subject.read(key).should be_nil
+      subject.write key, true
+      subject.read(key).should eq('true')
+
+      subject.write key, 22
+      subject.read(key).should eq('22')
+
+      subject.delete(key)
+      subject.read(key).should be_nil
+    end
+  end
+
+  context "working with sets" do
+    it "always uses strings" do
+      subject.set_add key, 1
+      subject.set_add key, 2
+      subject.set_members(key).should eq(Set['1', '2'])
+      subject.set_delete key, 2
+      subject.set_members(key).should eq(Set['1'])
+    end
+  end
+
+  context "integration spot-checks" do
+    let(:instance) { Flipper.new(subject) }
+    let(:feature) { instance[:feature] }
+    let(:actor) { Struct.new(:id).new(1) }
+
+    context "percentage of actors" do
+      let(:percentage) { instance.actors(10) }
+      it_should_behave_like 'a working percentage'
+    end
+
+    context "random percentage" do
+      let(:percentage) { instance.random(10) }
+      it_should_behave_like 'a working percentage'
+    end
+  end
 end