flipper 0.24.1 → 1.3.0

data/lib/flipper/exporter.rb

@@ -0,0 +1,17 @@
+require "flipper/exporters/json/v1"
+
+module Flipper
+  module Exporter
+    extend self
+
+    FORMATTERS = {
+      json: {
+        1 => Flipper::Exporters::Json::V1,
+      }
+    }.freeze
+
+    def build(format: :json, version: 1)
+      FORMATTERS.fetch(format).fetch(version).new
+    end
+  end
+end

data/lib/flipper/exporters/json/export.rb

@@ -0,0 +1,32 @@
+require "flipper/export"
+require "flipper/typecast"
+
+module Flipper
+  module Exporters
+    module Json
+      # Raised when the contents of the export are not valid.
+      class InvalidError < StandardError; end
+      class JsonError < InvalidError; end
+
+      # Internal: JSON export class that knows how to build features hash
+      # from data.
+      class Export < ::Flipper::Export
+        def initialize(contents:, version: 1)
+          super contents: contents, version: version, format: :json
+        end
+
+        # Public: The features hash identical to calling get_all on adapter.
+        def features
+          @features ||= begin
+            features = Typecast.from_json(contents).fetch("features")
+            Typecast.features_hash(features)
+          rescue JSON::ParserError
+            raise JsonError
+          rescue
+            raise InvalidError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flipper/exporters/json/v1.rb

@@ -0,0 +1,33 @@
+require "json"
+require "flipper/exporters/json/export"
+
+module Flipper
+  module Exporters
+    module Json
+      class V1
+        VERSION = 1
+
+        def call(adapter)
+          features = adapter.get_all
+
+          # Convert sets to arrays for json
+          features.each do |feature_key, gates|
+            gates.each do |key, value|
+              case value
+              when Set
+                features[feature_key][key] = value.to_a
+              end
+            end
+          end
+
+          json = Typecast.to_json({
+            version: VERSION,
+            features: features,
+          })
+
+          Json::Export.new(contents: json, version: VERSION)
+        end
+      end
+    end
+  end
+end

data/lib/flipper/expression/builder.rb

@@ -0,0 +1,73 @@
+module Flipper
+  class Expression
+    module Builder
+      def build(object)
+        Expression.build(object)
+      end
+
+      def add(*expressions)
+        group? ? build(name => args + expressions.flatten) : any.add(*expressions)
+      end
+
+      def remove(*expressions)
+        group? ? build(name => args - expressions.flatten) : any.remove(*expressions)
+      end
+
+      def any
+        any? ? self : build({ Any: [self] })
+      end
+
+      def all
+        all? ? self : build({ All: [self] })
+      end
+
+      def equal(object)
+        build({ Equal: [self, object] })
+      end
+      alias eq equal
+
+      def not_equal(object)
+        build({ NotEqual: [self, object] })
+      end
+      alias neq not_equal
+
+      def greater_than(object)
+        build({ GreaterThan: [self, object] })
+      end
+      alias gt greater_than
+
+      def greater_than_or_equal_to(object)
+        build({ GreaterThanOrEqualTo: [self, object] })
+      end
+      alias gte greater_than_or_equal_to
+      alias greater_than_or_equal greater_than_or_equal_to
+
+      def less_than(object)
+        build({ LessThan: [self, object] })
+      end
+      alias lt less_than
+
+      def less_than_or_equal_to(object)
+        build({ LessThanOrEqualTo: [self, object] })
+      end
+      alias lte less_than_or_equal_to
+      alias less_than_or_equal less_than_or_equal_to
+
+      def percentage_of_actors(object)
+        build({ PercentageOfActors: [self, build(object)] })
+      end
+
+      def any?
+        is_a?(Expression) && function == Expressions::Any
+      end
+
+      def all?
+        is_a?(Expression) && function == Expressions::All
+      end
+
+      def group?
+        any? || all?
+      end
+    end
+  end
+end

data/lib/flipper/expression/constant.rb

@@ -0,0 +1,25 @@
+module Flipper
+  class Expression
+    # Public: A constant value like a "string", Number (1, 3.5), Boolean (true, false).
+    #
+    # Implements the same interface as Expression
+    class Constant
+      include Expression::Builder
+
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      def evaluate(_ = nil)
+        value
+      end
+
+      def eql?(other)
+        other.is_a?(self.class) && other.value == value
+      end
+      alias_method :==, :eql?
+    end
+  end
+end

data/lib/flipper/expression.rb

@@ -0,0 +1,71 @@
+require "flipper/expression/builder"
+require "flipper/expression/constant"
+
+module Flipper
+  class Expression
+    include Builder
+
+    def self.build(object)
+      return object if object.is_a?(self) || object.is_a?(Constant)
+
+      case object
+      when Hash
+        name = object.keys.first
+        args = object.values.first
+        unless name
+          raise ArgumentError, "#{object.inspect} cannot be converted into an expression"
+        end
+
+        new(name, Array(args).map { |o| build(o) })
+      when String, Numeric, FalseClass, TrueClass
+        Expression::Constant.new(object)
+      when Symbol
+        Expression::Constant.new(object.to_s)
+      else
+        raise ArgumentError, "#{object.inspect} cannot be converted into an expression"
+      end
+    end
+
+    # Use #build
+    private_class_method :new
+
+    attr_reader :name, :function, :args
+
+    def initialize(name, args = [])
+      @name = name.to_s
+      @function = Expressions.const_get(name)
+      @args = args
+    end
+
+    def evaluate(context = {})
+      if call_with_context?
+        function.call(*args.map {|arg| arg.evaluate(context) }, context: context)
+      else
+        function.call(*args.map {|arg| arg.evaluate(context) })
+      end
+    end
+
+    def eql?(other)
+      other.is_a?(self.class) && @function == other.function && @args == other.args
+    end
+    alias_method :==, :eql?
+
+    def value
+      {
+        name => args.map(&:value)
+      }
+    end
+
+    private
+
+    def call_with_context?
+      function.method(:call).parameters.any? do |type, name|
+        name == :context && [:key, :keyreq].include?(type)
+      end
+    end
+  end
+end
+
+Dir[File.join(File.dirname(__FILE__), 'expressions', '*.rb')].sort.each do |file|
+  require "flipper/expressions/#{File.basename(file, '.rb')}"
+end

data/lib/flipper/expressions/all.rb

@@ -0,0 +1,11 @@
+require "flipper/expression"
+
+module Flipper
+  module Expressions
+    class All
+      def self.call(*args)
+        args.all?
+      end
+    end
+  end
+end

data/lib/flipper/expressions/any.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class Any
+      def self.call(*args)
+        args.any?
+      end
+    end
+  end
+end

data/lib/flipper/expressions/boolean.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class Boolean
+      def self.call(value)
+        Flipper::Typecast.to_boolean(value)
+      end
+    end
+  end
+end

data/lib/flipper/expressions/comparable.rb

@@ -0,0 +1,13 @@
+module Flipper
+  module Expressions
+    class Comparable
+      def self.operator
+        raise NotImplementedError
+      end
+
+      def self.call(left, right)
+        left.respond_to?(operator) && right.respond_to?(operator) && left.public_send(operator, right)
+      end
+    end
+  end
+end

data/lib/flipper/expressions/duration.rb

@@ -0,0 +1,28 @@
+module Flipper
+  module Expressions
+    class Duration
+      SECONDS_PER = {
+        "second" => 1,
+        "minute" => 60,
+        "hour" => 3600,
+        "day" => 86400,
+        "week" => 604_800,
+        "month" => 2_629_746,  # 1/12 of a gregorian year
+        "year" => 31_556_952 # length of a gregorian year (365.2425 days)
+      }.freeze
+
+      def self.call(scalar, unit = 'second')
+        unit = unit.to_s.downcase.chomp("s")
+
+        unless scalar.is_a?(Numeric)
+          raise ArgumentError.new("Duration value must be a number but was #{scalar.inspect}")
+        end
+        unless SECONDS_PER[unit]
+          raise ArgumentError.new("Duration unit #{unit.inspect} must be one of: #{SECONDS_PER.keys.join(', ')}")
+        end
+
+        scalar * SECONDS_PER[unit]
+      end
+    end
+  end
+end

data/lib/flipper/expressions/equal.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class Equal < Comparable
+      def self.operator
+        :==
+      end
+    end
+  end
+end

data/lib/flipper/expressions/greater_than.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class GreaterThan < Comparable
+      def self.operator
+        :>
+      end
+    end
+  end
+end

data/lib/flipper/expressions/greater_than_or_equal_to.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class GreaterThanOrEqualTo < Comparable
+      def self.operator
+        :>=
+      end
+    end
+  end
+end

data/lib/flipper/expressions/less_than.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class LessThan < Comparable
+      def self.operator
+        :<
+      end
+    end
+  end
+end

data/lib/flipper/expressions/less_than_or_equal_to.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class LessThanOrEqualTo < Comparable
+      def self.operator
+        :<=
+      end
+    end
+  end
+end

data/lib/flipper/expressions/not_equal.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class NotEqual < Comparable
+      def self.operator
+        :!=
+      end
+    end
+  end
+end

data/lib/flipper/expressions/now.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class Now
+      def self.call
+        ::Time.now.utc
+      end
+    end
+  end
+end

data/lib/flipper/expressions/number.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class Number
+      def self.call(value)
+        Flipper::Typecast.to_number(value)
+      end
+    end
+  end
+end

data/lib/flipper/expressions/percentage.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class Percentage
+      def self.call(value)
+        value.to_f.clamp(0, 100)
+      end
+    end
+  end
+end

data/lib/flipper/expressions/percentage_of_actors.rb

@@ -0,0 +1,12 @@
+module Flipper
+  module Expressions
+    class PercentageOfActors
+      SCALING_FACTOR = 1_000
+
+      def self.call(text, percentage, context: {})
+        prefix = context[:feature_name] || ""
+        Zlib.crc32("#{prefix}#{text}") % (100 * SCALING_FACTOR) < percentage * SCALING_FACTOR
+      end
+    end
+  end
+end

data/lib/flipper/expressions/property.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class Property
+      def self.call(key, context:)
+        context.dig(:properties, key.to_s)
+      end
+    end
+  end
+end

data/lib/flipper/expressions/random.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class Random
+      def self.call(max = 0)
+        rand max
+      end
+    end
+  end
+end

data/lib/flipper/expressions/string.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class String
+      def self.call(value)
+        value.to_s
+      end
+    end
+  end
+end

data/lib/flipper/expressions/time.rb

@@ -0,0 +1,9 @@
+module Flipper
+  module Expressions
+    class Time
+      def self.call(value)
+        ::Time.parse(value)
+      end
+    end
+  end
+end

data/lib/flipper/feature.rb

@@ -96,18 +96,19 @@ module Flipper
       instrument(:clear) { adapter.clear(self) }
     end
 
-    # Public: Check if a feature is enabled for a thing.
+    # Public: Check if a feature is enabled for zero or more actors.
     #
     # Returns true if enabled, false if not.
-    def enabled?(thing = nil)
-      instrument(:enabled?) do |payload|
-        values = gate_values
-        thing = gate(:actor).wrap(thing) unless thing.nil?
-        payload[:thing] = thing
+    def enabled?(*actors)
+      actors = actors.flatten.compact.map { |actor| Types::Actor.wrap(actor) }
+      actors = nil if actors.empty?
+
+      # thing is left for backwards compatibility
+      instrument(:enabled?, thing: actors&.first, actors: actors) do |payload|
         context = FeatureCheckContext.new(
           feature_name: @name,
-          values: values,
-          thing: thing
+          values: gate_values,
+          actors: actors
         )
 
         if open_gate = gates.detect { |gate| gate.open?(context) }
@@ -119,6 +120,28 @@ module Flipper
       end
     end
 
+    # Public: Enables an expression_to_add for a feature.
+    #
+    # expression - an Expression or Hash that can be converted to an expression.
+    #
+    # Returns result of enable.
+    def enable_expression(expression)
+      enable Expression.build(expression)
+    end
+
+    # Public: Add an expression for a feature.
+    #
+    # expression_to_add - an expression or Hash that can be converted to an expression.
+    #
+    # Returns result of enable.
+    def add_expression(expression_to_add)
+      if (current_expression = expression)
+        enable current_expression.add(expression_to_add)
+      else
+        enable expression_to_add
+      end
+    end
+
     # Public: Enables a feature for an actor.
     #
     # actor - a Flipper::Types::Actor instance or an object that responds
@@ -159,6 +182,27 @@ module Flipper
       enable Types::PercentageOfActors.wrap(percentage)
     end
 
+    # Public: Disables an expression for a feature.
+    #
+    # expression - an expression or Hash that can be converted to an expression.
+    #
+    # Returns result of disable.
+    def disable_expression
+      disable Flipper.all # just need an expression to clear
+    end
+
+    # Public: Remove an expression from a feature. Does nothing if no expression is
+    # currently enabled.
+    #
+    # expression - an Expression or Hash that can be converted to an expression.
+    #
+    # Returns result of enable or nil (if no expression enabled).
+    def remove_expression(expression_to_remove)
+      if (current_expression = expression)
+        enable current_expression.remove(expression_to_remove)
+      end
+    end
+
     # Public: Disables a feature for an actor.
     #
     # actor - a Flipper::Types::Actor instance or an object that responds
@@ -207,7 +251,7 @@ module Flipper
 
       if values.boolean || values.percentage_of_time == 100
         :on
-      elsif non_boolean_gates.detect { |gate| gate.enabled?(values[gate.key]) }
+      elsif non_boolean_gates.detect { |gate| gate.enabled?(values.send(gate.key)) }
         :conditional
       else
         :off
@@ -232,7 +276,8 @@ module Flipper
 
     # Public: Returns the raw gate values stored by the adapter.
     def gate_values
-      GateValues.new(adapter.get(self))
+      adapter_values = adapter.get(self)
+      GateValues.new(adapter_values)
     end
 
     # Public: Get groups enabled for this feature.
@@ -250,6 +295,10 @@ module Flipper
       Flipper.groups - enabled_groups
     end
 
+    def expression
+      Flipper::Expression.build(expression_value) if expression_value
+    end
+
     # Public: Get the adapter value for the groups gate.
     #
     # Returns Set of String group names.
@@ -257,6 +306,13 @@ module Flipper
       gate_values.groups
     end
 
+    # Public: Get the adapter value for the expression gate.
+    #
+    # Returns expression.
+    def expression_value
+      gate_values.expression
+    end
+
     # Public: Get the adapter value for the actors gate.
     #
     # Returns Set of String flipper_id's.
@@ -290,7 +346,7 @@ module Flipper
     # Returns an Array of Flipper::Gate instances.
     def enabled_gates
       values = gate_values
-      gates.select { |gate| gate.enabled?(values[gate.key]) }
+      gates.select { |gate| gate.enabled?(values.send(gate.key)) }
     end
 
     # Public: Get the names of the enabled gates.
@@ -339,37 +395,42 @@ module Flipper
     #
     # Returns an array of gates
     def gates
-      @gates ||= [
-        Gates::Boolean.new,
-        Gates::Actor.new,
-        Gates::PercentageOfActors.new,
-        Gates::PercentageOfTime.new,
-        Gates::Group.new,
-      ]
+      @gates ||= gates_hash.values.freeze
+    end
+
+    def gates_hash
+      @gates_hash ||= {
+        boolean: Gates::Boolean.new,
+        expression: Gates::Expression.new,
+        actor: Gates::Actor.new,
+        percentage_of_actors: Gates::PercentageOfActors.new,
+        percentage_of_time: Gates::PercentageOfTime.new,
+        group: Gates::Group.new,
+      }.freeze
     end
 
     # 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 }
+      gates_hash[name.to_sym]
     end
 
-    # Public: Find the gate that protects a thing.
+    # Public: Find the gate that protects an actor.
     #
-    # thing - The object for which you would like to find a gate
+    # actor - 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)
-      gates.detect { |gate| gate.protects?(thing) } || raise(GateNotFound, thing)
+    # Raises Flipper::GateNotFound if no gate found for actor
+    def gate_for(actor)
+      gates.detect { |gate| gate.protects?(actor) } || raise(GateNotFound, actor)
     end
 
     private
 
     # Private: Instrument a feature operation.
-    def instrument(operation)
-      @instrumenter.instrument(InstrumentationName) do |payload|
+    def instrument(operation, initial_payload = {})
+      @instrumenter.instrument(InstrumentationName, initial_payload) do |payload|
         payload[:feature_name] = name
         payload[:operation] = operation
         payload[:result] = yield(payload) if block_given?