flipper 0.6.3 → 0.7.0.beta1

data/lib/flipper/feature.rb

@@ -1,17 +1,21 @@
 require 'flipper/errors'
 require 'flipper/type'
 require 'flipper/gate'
+require 'flipper/gate_values'
 require 'flipper/instrumenters/noop'
 
 module Flipper
   class Feature
-    # Private: The name of instrumentation events.
+    # Private: The name of feature instrumentation events.
     InstrumentationName = "feature_operation.#{InstrumentationNamespace}"
 
+    # Private: The name of gate instrumentation events.
+    GateInstrumentationName = "gate_operation.#{InstrumentationNamespace}"
+
     # Public: The name of the feature.
     attr_reader :name
 
-    # Internal: Name converted to value safe for adapter.
+    # Public: Name converted to value safe for adapter.
     attr_reader :key
 
     # Private: The adapter this feature should use.
@@ -37,7 +41,7 @@ module Flipper
 
     # Public: Enable this feature for something.
     #
-    # Returns the result of Flipper::Gate#enable.
+    # Returns the result of Adapter#enable.
     def enable(thing = Types::Boolean.new(true))
       instrument(:enable, thing) { |payload|
         adapter.add self
@@ -51,7 +55,7 @@ module Flipper
 
     # Public: Disable this feature for something.
     #
-    # Returns the result of Flipper::Gate#disable.
+    # Returns the result of Adapter#disable.
     def disable(thing = Types::Boolean.new(false))
       instrument(:disable, thing) { |payload|
         adapter.add self
@@ -72,55 +76,214 @@ module Flipper
     # Returns true if enabled, false if not.
     def enabled?(thing = nil)
       instrument(:enabled?, thing) { |payload|
-        gate_values = adapter.get(self)
+        values = gate_values
 
-        gate = gates.detect { |gate|
-          gate.open?(thing, gate_values[gate.key])
+        open_gate = gates.detect { |gate|
+          instrument_gate(gate, :open?, thing) { |gate_payload|
+            gate.open?(thing, values[gate.key], feature_name: @name)
+          }
         }
 
-        if gate.nil?
+        if open_gate.nil?
           false
         else
-          payload[:gate_name] = gate.name
+          payload[:gate_name] = open_gate.name
           true
         end
       }
     end
 
-    # Public
+    # Public: Enables a feature for an actor.
+    #
+    # actor - a Flipper::Types::Actor instance or an object that responds
+    #         to flipper_id.
+    #
+    # Returns result of enable.
+    def enable_actor(actor)
+      enable Types::Actor.wrap(actor)
+    end
+
+    # Public: Enables a feature for a group.
+    #
+    # group - a Flipper::Types::Group instance or a String or Symbol name of a
+    #         registered group.
+    #
+    # Returns result of enable.
+    def enable_group(group)
+      enable Flipper::Types::Group.wrap(group)
+    end
+
+    # Public: Enables a feature a percentage of time.
+    #
+    # percentage - a Flipper::Types::PercentageOfTime instance or an object that
+    #              responds to to_i.
+    #
+    # Returns result of enable.
+    def enable_percentage_of_time(percentage)
+      enable Types::PercentageOfTime.wrap(percentage)
+    end
+
+    # Public: Enables a feature for a percentage of actors.
+    #
+    # percentage - a Flipper::Types::PercentageOfTime instance or an object that
+    #              responds to to_i.
+    #
+    # Returns result of enable.
+    def enable_percentage_of_actors(percentage)
+      enable Types::PercentageOfActors.wrap(percentage)
+    end
+
+    # Public: Disables a feature for an actor.
+    #
+    # actor - a Flipper::Types::Actor instance or an object that responds
+    #         to flipper_id.
+    #
+    # Returns result of disable.
+    def disable_actor(actor)
+      disable Types::Actor.wrap(actor)
+    end
+
+    # Public: Disables a feature for a group.
+    #
+    # group - a Flipper::Types::Group instance or a String or Symbol name of a
+    #         registered group.
+    #
+    # Returns result of disable.
+    def disable_group(group)
+      disable Flipper::Types::Group.wrap(group)
+    end
+
+    # Public: Disables a feature a percentage of time.
+    #
+    # percentage - a Flipper::Types::PercentageOfTime instance or an object that
+    #              responds to to_i.
+    #
+    # Returns result of disable.
+    def disable_percentage_of_time
+      disable Types::PercentageOfTime.new(0)
+    end
+
+    # Public: Disables a feature for a percentage of actors.
+    #
+    # percentage - a Flipper::Types::PercentageOfTime instance or an object that
+    #              responds to to_i.
+    #
+    # Returns result of disable.
+    def disable_percentage_of_actors
+      disable Types::PercentageOfActors.new(0)
+    end
+
+    # Public: Returns state for feature (:on, :off, or :conditional).
     def state
-      gate_values = adapter.get(self)
-      boolean_value = gate_values[:boolean]
+      values = gate_values
 
-      if boolean_gate.enabled?(boolean_value)
+      if boolean_gate.enabled?(values.boolean)
         :on
-      elsif conditional_gates(gate_values).any?
+      elsif conditional_gates(values).any?
         :conditional
       else
         :off
       end
     end
 
-    # Public
+    # Public: Is the feature fully enabled.
+    def on?
+      state == :on
+    end
+
+    # Public: Is the feature fully disabled.
+    def off?
+      state == :off
+    end
+
+    # Public: Is the feature conditionally enabled for a given actor, group,
+    # percentage of actors or percentage of the time.
+    def conditional?
+      state == :conditional
+    end
+
+    # Public: Human readable description of the enabled-ness of the feature.
     def description
-      gate_values = adapter.get(self)
-      boolean_value = gate_values[:boolean]
-      conditional_gates = conditional_gates(gate_values)
+      values = gate_values
+      conditional_gates = conditional_gates(values)
 
-      if boolean_gate.enabled?(boolean_value)
-        boolean_gate.description(boolean_value).capitalize
-      elsif conditional_gates.any?
+      if boolean_gate.enabled?(values.boolean) || !conditional_gates.any?
+        boolean_gate.description(values.boolean).capitalize
+      else
         fragments = conditional_gates.map { |gate|
-          value = gate_values[gate.key]
+          value = values[gate.key]
           gate.description(value)
         }
 
         "Enabled for #{fragments.join(', ')}"
-      else
-        boolean_gate.description(boolean_value).capitalize
       end
     end
 
+    # Public: Returns the raw gate values stored by the adapter.
+    def gate_values
+      GateValues.new(adapter.get(self))
+    end
+
+    # Public: Get groups enabled for this feature.
+    #
+    # Returns Set of Flipper::Types::Group instances.
+    def enabled_groups
+      groups_value.map { |name| Flipper.group(name) }.to_set
+    end
+    alias_method :groups, :enabled_groups
+
+    # Public: Get groups not enabled for this feature.
+    #
+    # Returns Set of Flipper::Types::Group instances.
+    def disabled_groups
+      Flipper.groups - enabled_groups
+    end
+
+    # Public: Get the adapter value for the groups gate.
+    #
+    # Returns Set of String group names.
+    def groups_value
+      gate_values.groups
+    end
+
+    # Public: Get the adapter value for the actors gate.
+    #
+    # Returns Set of String flipper_id's.
+    def actors_value
+      gate_values.actors
+    end
+
+    # Public: Get the adapter value for the boolean gate.
+    #
+    # Returns true or false.
+    def boolean_value
+      gate_values.boolean
+    end
+
+    # Public: Get the adapter value for the percentage of actors gate.
+    #
+    # Returns Integer greater than or equal to 0 and less than or equal to 100.
+    def percentage_of_actors_value
+      gate_values.percentage_of_actors
+    end
+
+    # Public: Get the adapter value for the percentage of time gate.
+    #
+    # Returns Integer greater than or equal to 0 and less than or equal to 100.
+    def percentage_of_time_value
+      gate_values.percentage_of_time
+    end
+
+    # Public: Returns the string representation of the feature.
+    def to_s
+      name.to_s
+    end
+
+    # Public: Identifier to be used in the url (a rails-ism).
+    def to_param
+      to_s
+    end
+
     # Public: Pretty string version for debugging.
     def inspect
       attributes = [
@@ -132,27 +295,27 @@ module Flipper
       "#<#{self.class.name}:#{object_id} #{attributes.join(', ')}>"
     end
 
-    # Internal: Gates to check to see if feature is enabled/disabled
+    # Public: Get all the gates used to determine enabled/disabled for the feature.
     #
     # Returns an array of gates
     def gates
       @gates ||= [
-        Gates::Boolean.new(@name, :instrumenter => @instrumenter),
-        Gates::Group.new(@name, :instrumenter => @instrumenter),
-        Gates::Actor.new(@name, :instrumenter => @instrumenter),
-        Gates::PercentageOfActors.new(@name, :instrumenter => @instrumenter),
-        Gates::PercentageOfRandom.new(@name, :instrumenter => @instrumenter),
+        Gates::Boolean.new,
+        Gates::Group.new,
+        Gates::Actor.new,
+        Gates::PercentageOfActors.new,
+        Gates::PercentageOfTime.new,
       ]
     end
 
-    # Internal: Finds a gate by name.
+    # Public: Find a gate by name.
     #
     # Returns a Flipper::Gate if found, nil if not.
     def gate(name)
       gates.detect { |gate| gate.name == name.to_sym }
     end
 
-    # Internal: Find the gate that protects a thing.
+    # Public: Find the gate that protects a thing.
     #
     # thing - The object for which you would like to find a gate
     #
@@ -163,25 +326,27 @@ module Flipper
         raise(GateNotFound.new(thing))
     end
 
-    # Private
+    private
+
+    # Private: Get the boolean gate.
     def boolean_gate
       @boolean_gate ||= gate(:boolean)
     end
 
-    # Private
+    # Private: Get all gates except the boolean gate.
     def non_boolean_gates
       @non_boolean_gates ||= gates - [boolean_gate]
     end
 
-    # Private
+    # Private: Get all non boolean gates that are enabled in some way.
     def conditional_gates(gate_values)
-      @conditional_gates ||= non_boolean_gates.select { |gate|
+      non_boolean_gates.select { |gate|
         value = gate_values[gate.key]
         gate.enabled?(value)
       }
     end
 
-    # Private
+    # Private: Instrument a feature operation.
     def instrument(operation, thing)
       payload = {
         :feature_name => name,
@@ -193,5 +358,19 @@ module Flipper
         payload[:result] = yield(payload) if block_given?
       }
     end
+
+    # Private: Intrument a gate operation.
+    def instrument_gate(gate, operation, thing)
+      payload = {
+        :feature_name => @name,
+        :gate_name => gate.name,
+        :operation => operation,
+        :thing => thing,
+      }
+
+      @instrumenter.instrument(GateInstrumentationName, payload) {
+        payload[:result] = yield(payload) if block_given?
+      }
+    end
   end
 end

data/lib/flipper/gate.rb

@@ -1,23 +1,11 @@
 require 'forwardable'
-require 'flipper/instrumenters/noop'
 
 module Flipper
   class Gate
     extend Forwardable
 
-    # Private: The name of instrumentation events.
-    InstrumentationName = "gate_operation.#{InstrumentationNamespace}"
-
-    # Private
-    attr_reader :feature_name
-
-    # Private: What is used to instrument all the things.
-    attr_reader :instrumenter
-
     # Public
-    def initialize(feature_name, options = {})
-      @feature_name = feature_name
-      @instrumenter = options.fetch(:instrumenter, Flipper::Instrumenters::Noop)
+    def initialize(options = {})
     end
 
     # Public: The name of the gate. Implemented in subclass.
@@ -34,14 +22,6 @@ module Flipper
       raise 'Not implemented'
     end
 
-    def enable(thing)
-      raise 'Not implemented'
-    end
-
-    def disable(thing)
-      raise 'Not implemented'
-    end
-
     def enabled?(value)
       raise 'Not implemented'
     end
@@ -53,7 +33,7 @@ module Flipper
     # 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)
+    def open?(thing, value, options = {})
       false
     end
 
@@ -73,24 +53,12 @@ module Flipper
     # Public: Pretty string version for debugging.
     def inspect
       attributes = [
-        "feature_name=#{feature_name.inspect}",
+        "name=#{@name.inspect}",
+        "key=#{@key.inspect}",
+        "data_type=#{@data_type.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
 
@@ -98,4 +66,4 @@ require 'flipper/gates/actor'
 require 'flipper/gates/boolean'
 require 'flipper/gates/group'
 require 'flipper/gates/percentage_of_actors'
-require 'flipper/gates/percentage_of_random'
+require 'flipper/gates/percentage_of_time'

data/lib/flipper/gate_values.rb

@@ -0,0 +1,42 @@
+module Flipper
+  class GateValues
+    # Private: Array of instance variables that are readable through the []
+    # instance method.
+    LegitIvars = [
+      "boolean",
+      "actors",
+      "groups",
+      "percentage_of_time",
+      "percentage_of_actors",
+    ]
+
+    attr_reader :boolean
+    attr_reader :actors
+    attr_reader :groups
+    attr_reader :percentage_of_actors
+    attr_reader :percentage_of_time
+
+    def initialize(adapter_values)
+      @boolean = Typecast.to_boolean(adapter_values[:boolean])
+      @actors = Typecast.to_set(adapter_values[:actors])
+      @groups = Typecast.to_set(adapter_values[:groups])
+      @percentage_of_actors = Typecast.to_integer(adapter_values[:percentage_of_actors])
+      @percentage_of_time = Typecast.to_integer(adapter_values[:percentage_of_time])
+    end
+
+    def [](key)
+      return nil unless LegitIvars.include?(key.to_s)
+      instance_variable_get("@#{key}")
+    end
+
+    def eql?(other)
+      self.class.eql?(other.class) &&
+        boolean == other.boolean &&
+        actors == other.actors &&
+        groups == other.groups &&
+        percentage_of_actors == other.percentage_of_actors &&
+        percentage_of_time == other.percentage_of_time
+    end
+    alias_method :==, :eql?
+  end
+end