flipper 0.3.0 → 0.4.0

data/lib/flipper/errors.rb

@@ -1,11 +1,17 @@
 module Flipper
+  # Top level error that all other errors inherit from.
   class Error < StandardError; end
 
+  # Raised when gate can not be found for a thing.
   class GateNotFound < Error
     def initialize(thing)
       super "Could not find gate for #{thing.inspect}"
     end
   end
 
+  # Raised when attempting to declare a group name that has already been used.
   class DuplicateGroup < Error; end
+
+  # Raised when attempting to access a group that is not registered.
+  class GroupNotRegistered < Error; end
 end

data/lib/flipper/feature.rb

@@ -3,31 +3,72 @@ require 'flipper/errors'
 require 'flipper/type'
 require 'flipper/toggle'
 require 'flipper/gate'
+require 'flipper/instrumenters/noop'
 
 module Flipper
   class Feature
+    # Private: The name of instrumentation events.
+    InstrumentationName = "feature_operation.#{InstrumentationNamespace}"
+
+    # Internal: The name of the feature.
     attr_reader :name
+
+    # Private: The adapter this feature should use.
     attr_reader :adapter
 
-    def initialize(name, adapter)
+    # Private: What is being used to instrument all the things.
+    attr_reader :instrumenter
+
+    # Internal: Initializes a new feature instance.
+    #
+    # name - The Symbol or String name of the feature.
+    # adapter - The adapter that will be used to store details about this feature.
+    #
+    # options - The Hash of options.
+    #           :instrumenter - What to use to instrument all the things.
+    #
+    def initialize(name, adapter, options = {})
       @name = name
-      @adapter = Adapter.wrap(adapter)
+      @instrumenter = options.fetch(:instrumenter, Flipper::Instrumenters::Noop)
+      @adapter = Adapter.wrap(adapter, :instrumenter => @instrumenter)
     end
 
+    # Public: Enable this feature for something.
+    #
+    # Returns the result of Flipper::Gate#enable.
     def enable(thing = Types::Boolean.new)
-      gate_for(thing).enable(thing)
+      instrument(:enable, thing) { |payload|
+        gate = gate_for(thing)
+        payload[:gate_name] = gate.name
+        gate.enable(thing)
+      }
     end
 
+    # Public: Disable this feature for something.
+    #
+    # Returns the result of Flipper::Gate#disable.
     def disable(thing = Types::Boolean.new)
-      gate_for(thing).disable(thing)
+      instrument(:disable, thing) { |payload|
+        gate = gate_for(thing)
+        payload[:gate_name] = gate.name
+        gate.disable(thing)
+      }
     end
 
-    def enabled?(actor = nil)
-      !! catch(:short_circuit) { gates.detect { |gate| gate.open?(actor) } }
-    end
+    # Public: Check if a feature is enabled for a thing.
+    #
+    # Returns true if enabled, false if not.
+    def enabled?(thing = nil)
+      instrument(:enabled?, thing) { |payload|
+        gate = gates.detect { |gate| gate.open?(thing) }
 
-    def disabled?(actor = nil)
-      !enabled?(actor)
+        if gate.nil?
+          false
+        else
+          payload[:gate_name] = gate.name
+          true
+        end
+      }
     end
 
     # Internal: Gates to check to see if feature is enabled/disabled
@@ -35,27 +76,84 @@ module Flipper
     # Returns an array of gates
     def gates
       @gates ||= [
-        Gates::Boolean.new(self),
-        Gates::Group.new(self),
-        Gates::Actor.new(self),
-        Gates::PercentageOfActors.new(self),
-        Gates::PercentageOfRandom.new(self),
+        Gates::Boolean.new(self, :instrumenter => @instrumenter),
+        Gates::Group.new(self, :instrumenter => @instrumenter),
+        Gates::Actor.new(self, :instrumenter => @instrumenter),
+        Gates::PercentageOfActors.new(self, :instrumenter => @instrumenter),
+        Gates::PercentageOfRandom.new(self, :instrumenter => @instrumenter),
       ]
     end
 
-    # Internal: Returns gate that protects thing
+    # Internal: Find the gate that protects a thing.
     #
     # thing - The object for which you would like to find a gate
     #
+    # Returns a Flipper::Gate.
     # Raises Flipper::GateNotFound if no gate found for thing
     def gate_for(thing)
-      find_gate(thing) || raise(GateNotFound.new(thing))
+      gates.detect { |gate| gate.protects?(thing) } ||
+        raise(GateNotFound.new(thing))
+    end
+
+    # Public: Pretty string version for debugging.
+    def inspect
+      attributes = [
+        "name=#{name.inspect}",
+        "state=#{state.inspect}",
+        "adapter=#{adapter.name.inspect}",
+      ]
+      "#<#{self.class.name}:#{object_id} #{attributes.join(', ')}>"
+    end
+
+    # Public
+    def state
+      if boolean_gate.enabled?
+        :on
+      elsif conditional_gates.any?
+        :conditional
+      else
+        :off
+      end
+    end
+
+    # Public
+    def description
+      if boolean_gate.enabled?
+        boolean_gate.description.capitalize
+      elsif conditional_gates.any?
+        fragments = conditional_gates.map(&:description)
+        "Enabled for #{fragments.join(', ')}"
+      else
+        boolean_gate.description.capitalize
+      end
+    end
+
+    # Private
+    def boolean_gate
+      @boolean_gate ||= gates.detect { |gate| gate.name == :boolean }
+    end
+
+    # Private
+    def non_boolean_gates
+      @non_boolean_gates ||= gates - [boolean_gate]
+    end
+
+    # Private
+    def conditional_gates
+      @conditional_gates ||= non_boolean_gates.select { |gate| gate.enabled? }
     end
 
-    private
+    # Private
+    def instrument(operation, thing)
+      payload = {
+        :feature_name => name,
+        :operation => operation,
+        :thing => thing,
+      }
 
-    def find_gate(thing)
-      gates.detect { |gate| gate.protects?(thing) }
+      @instrumenter.instrument(InstrumentationName, payload) {
+        payload[:result] = yield(payload) if block_given?
+      }
     end
   end
 end

data/lib/flipper/gate.rb

@@ -1,45 +1,113 @@
 require 'forwardable'
 require 'flipper/key'
+require 'flipper/instrumenters/noop'
 
 module Flipper
   class Gate
     extend Forwardable
 
+    # Private: The name of instrumentation events.
+    InstrumentationName = "gate_operation.#{InstrumentationNamespace}"
+
+    # Private
     attr_reader :feature
 
+    # Private: What is used to instrument all the things.
+    attr_reader :instrumenter
+
     def_delegator :@feature, :adapter
 
-    def initialize(feature)
+    # Public
+    def initialize(feature, options = {})
       @feature = feature
+      @instrumenter = options.fetch(:instrumenter, Flipper::Instrumenters::Noop)
+    end
+
+    # Public: The name of the gate. Implemented in subclass.
+    def name
+      raise 'Not implemented'
     end
 
+    # Private: The piece of the adapter key that is unique to the gate class.
+    # Implemented in subclass.
     def key
-      @key ||= Key.new(@feature.name, type_key)
+      raise 'Not implemented'
     end
 
+    # Internal: The key where details about this gate can be retrieved from the
+    # adapter.
+    def adapter_key
+      @key ||= Key.new(@feature.name, key)
+    end
+
+    # Internal: The toggle class to use for this gate.
     def toggle_class
       Toggles::Value
     end
 
+    # Internal: The toggle to use to enable/disable this gate.
     def toggle
       @toggle ||= toggle_class.new(self)
     end
 
-    def protects?(thing)
+    # Internal: Check if a gate is open for a thing. Implemented in subclass.
+    #
+    # Returns true if gate open for thing, false if not.
+    def open?(thing)
       false
     end
 
-    def match?(actor)
+    # Internal: Check if a gate is protects a thing. Implemented in subclass.
+    #
+    # Returns true if gate protects thing, false if not.
+    def protects?(thing)
       false
     end
 
+    # Internal: Enable this gate for a thing.
+    #
+    # Returns the result of Flipper::Toggle#enable.
     def enable(thing)
       toggle.enable(thing)
     end
 
+    # Internal: Disable this gate for a thing.
+    #
+    # Returns the result of Flipper::Toggle#disable.
     def disable(thing)
       toggle.disable(thing)
     end
+
+    def enabled?
+      toggle.enabled?
+    end
+
+    # Public: Pretty string version for debugging.
+    def inspect
+      attributes = [
+        "feature=#{feature.name.inspect}",
+        "description=#{description.inspect}",
+        "adapter=#{adapter.name.inspect}",
+        "adapter_key=#{adapter_key.inspect}",
+        "toggle_class=#{toggle_class.inspect}",
+        "toggle_value=#{toggle.value.inspect}",
+      ]
+      "#<#{self.class.name}:#{object_id} #{attributes.join(', ')}>"
+    end
+
+    # Private
+    def instrument(operation, thing)
+      payload = {
+        :thing => thing,
+        :operation => operation,
+        :gate_name => name,
+        :feature_name => @feature.name,
+      }
+
+      @instrumenter.instrument(InstrumentationName, payload) {
+        payload[:result] = yield(payload) if block_given?
+      }
+    end
   end
 end
 

data/lib/flipper/gates/actor.rb

@@ -1,29 +1,58 @@
 module Flipper
   module Gates
     class Actor < Gate
-      Key = :actors
+      # Internal: The name of the gate. Used for instrumentation, etc.
+      def name
+        :actor
+      end
 
-      def type_key
-        Key
+      # Internal: The piece of the adapter key that is unique to the gate class.
+      def key
+        :actors
       end
 
+      # Internal: The toggle class used to enable/disable the gate for a thing.
       def toggle_class
         Toggles::Set
       end
 
-      def open?(actor)
-        return if actor.nil?
-        return unless Types::Actor.wrappable?(actor)
-        actor = Types::Actor.wrap(actor)
-        identifiers.include?(actor.identifier)
+      # 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|
+          if thing.nil?
+            false
+          else
+            if Types::Actor.wrappable?(thing)
+              actor = Types::Actor.wrap(thing)
+              enabled_actor_ids = toggle.value
+              enabled_actor_ids.include?(actor.value)
+            else
+              false
+            end
+          end
+        }
       end
 
-      def identifiers
-        toggle.value
+      def protects?(thing)
+        Types::Actor.wrappable?(thing)
       end
 
-      def protects?(thing)
-        thing.is_a?(Flipper::Types::Actor)
+      def enable(thing)
+        super Types::Actor.wrap(thing)
+      end
+
+      def disable(thing)
+        super Types::Actor.wrap(thing)
+      end
+
+      def description
+        if enabled?
+          "actors (#{toggle.value.to_a.sort.join(', ')})"
+        else
+          'disabled'
+        end
       end
     end
   end

data/lib/flipper/gates/boolean.rb

@@ -1,29 +1,39 @@
 module Flipper
   module Gates
     class Boolean < Gate
-      Key = :boolean
+      # Internal: The name of the gate. Used for instrumentation, etc.
+      def name
+        :boolean
+      end
 
-      def type_key
-        Key
+      # Internal: The piece of the adapter key that is unique to the gate class.
+      def key
+        :boolean
       end
 
+      # Internal: The toggle class used to enable/disable the gate for a thing.
       def toggle_class
         Toggles::Boolean
       end
 
-      def open?(actor)
-        value = toggle.value
-
-        if value.nil?
-          false
-        else
-          throw :short_circuit, !!value
-        end
+      # 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| toggle.value }
       end
 
       def protects?(thing)
         thing.is_a?(Flipper::Types::Boolean)
       end
+
+      def description
+        if enabled?
+          'Enabled'
+        else
+          'Disabled'
+        end
+      end
     end
   end
 end

data/lib/flipper/gates/group.rb

@@ -1,31 +1,64 @@
 module Flipper
   module Gates
     class Group < Gate
-      Key = :groups
+      # Internal: The name of the gate. Used for instrumentation, etc.
+      def name
+        :group
+      end
 
-      def type_key
-        Key
+      # Internal: The piece of the adapter key that is unique to the gate class.
+      def key
+        :groups
       end
 
+      # Internal: The toggle class used to enable/disable the gate for a thing.
       def toggle_class
         Toggles::Set
       end
 
-      def open?(actor)
-        return if actor.nil?
-        groups.any? { |group| group.match?(actor) }
+      # 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|
+          if thing.nil?
+            false
+          else
+            enabled_groups.any? { |group| group.match?(thing) }
+          end
+        }
       end
 
-      def group_names
-        toggle.value
+      def protects?(thing)
+        thing.is_a?(Flipper::Types::Group)
       end
 
-      def groups
-        group_names.map { |name| Flipper.group(name) }.compact
+      def description
+        if enabled?
+          "groups (#{toggle.value.to_a.sort.join(', ')})"
+        else
+          'disabled'
+        end
       end
 
-      def protects?(thing)
-        thing.is_a?(Flipper::Types::Group)
+      # Private: Get all the enabled groups for this gate.
+      #
+      # Returns an Array of Flipper::Types::Group instances.
+      def enabled_groups
+        enabled_group_names.map { |name|
+          begin
+            Flipper.group(name)
+          rescue GroupNotRegistered
+            nil
+          end
+        }.compact
+      end
+
+      # Private: Get all the names of enabled groups.
+      #
+      # Returns a Set of the enabled group names.
+      def enabled_group_names
+        toggle.value
       end
     end
   end