flipper 0.16.0 → 1.4.0

data/lib/flipper/configuration.rb

@@ -1,7 +1,44 @@
 module Flipper
   class Configuration
-    def initialize
-      @default = -> { raise DefaultNotSet }
+    def initialize(options = {})
+      @builder = AdapterBuilder.new { store Flipper::Adapters::Memory }
+      @default = -> { Flipper.new(@builder.to_adapter) }
+    end
+
+    # The default adapter to use.
+    #
+    # Pass a block to assign the adapter, and invoke without a block to
+    # return the configured adapter instance.
+    #
+    #   Flipper.configure do |config|
+    #     config.adapter # => instance of default Memory adapter
+    #
+    #     # Configure it to use the ActiveRecord adapter
+    #     config.adapter do
+    #       require "flipper/adapters/active_record"
+    #       Flipper::Adapters::ActiveRecord.new
+    #     end
+    #
+    #     config.adapter # => instance of ActiveRecord adapter
+    #  end
+    #
+    def adapter(&block)
+      if block_given?
+        @builder.store(block)
+      else
+        @builder.to_adapter
+      end
+    end
+
+    # An adapter to use to augment the primary storage adapter. See `AdapterBuilder#use`
+    if RUBY_VERSION >= '3.0'
+      def use(klass, *args, **kwargs, &block)
+        @builder.use(klass, *args, **kwargs, &block)
+      end
+    else
+      def use(klass, *args, &block)
+        @builder.use(klass, *args, &block)
+      end
     end
 
     # Controls the default instance for flipper. When used with a block it
@@ -9,15 +46,15 @@ module Flipper
     # without a block, it performs a block invocation and returns the result.
     #
     #   configuration = Flipper::Configuration.new
-    #   configuration.default # => raises DefaultNotSet error.
+    #   configuration.default # => Flipper::DSL instance using Memory adapter
     #
-    #   # sets the default block to generate a new instance using Memory adapter
+    #   # sets the default block to generate a new instance using ActiveRecord adapter
     #   configuration.default do
-    #     require "flipper/adapters/memory"
-    #     Flipper.new(Flipper::Adapters::Memory.new)
+    #     require "flipper/adapters/active_record"
+    #     Flipper.new(Flipper::Adapters::ActiveRecord.new)
     #   end
     #
-    #   configuration.default # => Flipper::DSL instance using Memory adapter
+    #   configuration.default # => Flipper::DSL instance using ActiveRecord adapter
     #
     # Returns result of default block invocation if called without block. If
     # called with block, assigns the default block.
@@ -28,5 +65,15 @@ module Flipper
         @default.call
       end
     end
+
+    def statsd
+      require 'flipper/instrumentation/statsd_subscriber'
+      Flipper::Instrumentation::StatsdSubscriber.client
+    end
+
+    def statsd=(client)
+      require "flipper/instrumentation/statsd"
+      Flipper::Instrumentation::StatsdSubscriber.client = client
+    end
   end
 end

data/lib/flipper/dsl.rb

@@ -10,17 +10,19 @@ module Flipper
     # Private: What is being used to instrument all the things.
     attr_reader :instrumenter
 
-    def_delegators :@adapter, :memoize=, :memoizing?
+    def_delegators :@adapter, :memoize=, :memoizing?, :import, :export, :adapter_stack
 
     # Public: Returns a new instance of the DSL.
     #
     # adapter - The adapter that this DSL instance should use.
     # options - The Hash of options.
     #           :instrumenter - What should be used to instrument all the things.
+    #           :memoize - Should adapter be wrapped by memoize adapter or not.
     def initialize(adapter, options = {})
       @instrumenter = options.fetch(:instrumenter, Instrumenters::Noop)
-      memoized = Adapters::Memoizable.new(adapter)
-      @adapter = memoized
+      memoize = options.fetch(:memoize, true)
+      adapter = Adapters::Memoizable.new(adapter) if memoize
+      @adapter = adapter
       @memoized_features = {}
     end
 
@@ -44,6 +46,25 @@ module Flipper
       feature(name).enable(*args)
     end
 
+    # Public: Enable a feature for an expression.
+    #
+    # name - The String or Symbol name of the feature.
+    # expression - a Flipper::Expression instance or a Hash.
+    #
+    # Returns result of Feature#enable.
+    def enable_expression(name, expression)
+      feature(name).enable_expression(expression)
+    end
+
+    # Public: Add an expression to a feature.
+    #
+    # expression - an expression or Hash that can be converted to an expression.
+    #
+    # Returns result of enable.
+    def add_expression(name, expression)
+      feature(name).add_expression(expression)
+    end
+
     # Public: Enable a feature for an actor.
     #
     # name - The String or Symbol name of the feature.
@@ -98,6 +119,24 @@ module Flipper
       feature(name).disable(*args)
     end
 
+    # Public: Disable expression for feature.
+    #
+    # name - The String or Symbol name of the feature.
+    #
+    # Returns result of Feature#disable.
+    def disable_expression(name)
+      feature(name).disable_expression
+    end
+
+    # Public: Remove an expression from a feature.
+    #
+    # expression - an Expression or Hash that can be converted to an expression.
+    #
+    # Returns result of enable.
+    def remove_expression(name, expression)
+      feature(name).remove_expression(expression)
+    end
+
     # Public: Disable a feature for an actor.
     #
     # name - The String or Symbol name of the feature.
@@ -208,22 +247,6 @@ module Flipper
     # Returns an instance of Flipper::Feature.
     alias_method :[], :feature
 
-    # Public: Shortcut for getting a boolean type instance.
-    #
-    # value - The true or false value for the boolean.
-    #
-    # Returns a Flipper::Types::Boolean instance.
-    def boolean(value = true)
-      Types::Boolean.new(value)
-    end
-
-    # Public: Even shorter shortcut for getting a boolean type instance.
-    #
-    # value - The true or false value for the boolean.
-    #
-    # Returns a Flipper::Types::Boolean instance.
-    alias_method :bool, :boolean
-
     # Public: Access a flipper group by name.
     #
     # name - The String or Symbol name of the feature.
@@ -233,35 +256,14 @@ module Flipper
       Flipper.group(name)
     end
 
-    # Public: Wraps an object as a flipper actor.
-    #
-    # thing - The object that you would like to wrap.
-    #
-    # Returns an instance of Flipper::Types::Actor.
-    # Raises ArgumentError if thing does not respond to `flipper_id`.
-    def actor(thing)
-      Types::Actor.new(thing)
-    end
-
-    # Public: Shortcut for getting a percentage of time instance.
+    # Public: Gets the expression for the feature.
     #
-    # number - The percentage of time that should be enabled.
-    #
-    # Returns Flipper::Types::PercentageOfTime.
-    def time(number)
-      Types::PercentageOfTime.new(number)
-    end
-    alias_method :percentage_of_time, :time
-
-    # Public: Shortcut for getting a percentage of actors instance.
-    #
-    # number - The percentage of actors that should be enabled.
+    # name - The String or Symbol name of the feature.
     #
-    # Returns Flipper::Types::PercentageOfActors.
-    def actors(number)
-      Types::PercentageOfActors.new(number)
+    # Returns an instance of Flipper::Expression.
+    def expression(name)
+      feature(name).expression
     end
-    alias_method :percentage_of_actors, :actors
 
     # Public: Returns a Set of the known features for this adapter.
     #
@@ -270,8 +272,17 @@ module Flipper
       adapter.features.map { |name| feature(name) }.to_set
     end
 
-    def import(flipper)
-      adapter.import(flipper.adapter)
+    # Public: Does this adapter support writes or not.
+    def read_only?
+      adapter.read_only?
+    end
+
+    # Cloud DSL method that does nothing for open source version.
+    def sync
+    end
+
+    # Cloud DSL method that does nothing for open source version.
+    def sync_secret
     end
   end
 end

data/lib/flipper/engine.rb

@@ -0,0 +1,102 @@
+module Flipper
+  class Engine < Rails::Engine
+    def self.default_strict_value
+      value = ENV["FLIPPER_STRICT"]
+      if value.in?(["warn", "raise", "noop"])
+        value.to_sym
+      elsif value
+        Typecast.to_boolean(value) ? :raise : false
+      elsif Rails.env.production?
+        false
+      else
+        # Warn in development for now. Future versions may default to :raise in development and test
+        Rails.env.development? && :warn
+      end
+    end
+
+    paths["config/routes.rb"] = ["lib/flipper/cloud/routes.rb"]
+
+    config.before_configuration do
+      config.flipper = ActiveSupport::OrderedOptions.new.update(
+        env_key: ENV.fetch('FLIPPER_ENV_KEY', 'flipper'),
+        memoize: ENV.fetch('FLIPPER_MEMOIZE', 'true').casecmp('true').zero?,
+        preload: ENV.fetch('FLIPPER_PRELOAD', 'true').casecmp('true').zero?,
+        instrumenter: ENV.fetch('FLIPPER_INSTRUMENTER', 'ActiveSupport::Notifications').constantize,
+        log: ENV.fetch('FLIPPER_LOG', 'true').casecmp('true').zero?,
+        cloud_path: "_flipper",
+        strict: default_strict_value,
+        actor_limit: ENV["FLIPPER_ACTOR_LIMIT"]&.to_i || 100,
+        test_help: Flipper::Typecast.to_boolean(ENV["FLIPPER_TEST_HELP"] || Rails.env.test?),
+      )
+    end
+
+    initializer "flipper.properties" do
+      ActiveSupport.on_load(:active_record) do
+        require "flipper/model/active_record"
+        ActiveRecord::Base.include Flipper::Model::ActiveRecord
+      end
+    end
+
+    initializer "flipper.default", before: :load_config_initializers do |app|
+      # Load cloud secrets from Rails credentials
+      ENV["FLIPPER_CLOUD_TOKEN"] ||= app.credentials.dig(:flipper, :cloud_token)
+      ENV["FLIPPER_CLOUD_SYNC_SECRET"] ||= app.credentials.dig(:flipper, :cloud_sync_secret)
+
+      require 'flipper/cloud' if cloud?
+
+      Flipper.configure do |config|
+        config.default do
+          if cloud?
+            Flipper::Cloud.new(
+              local_adapter: config.adapter,
+              instrumenter: app.config.flipper.instrumenter
+            )
+          else
+            Flipper.new(config.adapter, instrumenter: app.config.flipper.instrumenter)
+          end
+        end
+      end
+    end
+
+    initializer "flipper.log", after: :load_config_initializers do |app|
+      flipper = app.config.flipper
+
+      if flipper.log && flipper.instrumenter == ActiveSupport::Notifications
+        require "flipper/instrumentation/log_subscriber"
+      end
+    end
+
+    initializer "flipper.adapters", after: :load_config_initializers do |app|
+      flipper = app.config.flipper
+
+      Flipper.configure do |config|
+        config.use Flipper::Adapters::Strict, flipper.strict if flipper.strict
+        config.use Flipper::Adapters::ActorLimit, flipper.actor_limit if flipper.actor_limit
+      end
+    end
+
+    initializer "flipper.memoizer", after: :load_config_initializers do |app|
+      flipper = app.config.flipper
+
+      if flipper.memoize
+        app.middleware.use Flipper::Middleware::Memoizer, {
+          env_key: flipper.env_key,
+          preload: flipper.preload,
+          if: flipper.memoize.respond_to?(:call) ? flipper.memoize : nil
+        }
+      end
+    end
+
+    initializer "flipper.test" do |app|
+      require "flipper/test_help" if app.config.flipper.test_help
+    end
+
+    def cloud?
+      !!ENV["FLIPPER_CLOUD_TOKEN"]
+    end
+
+    def self.deprecated_rails_version?
+      Gem::Version.new(Rails.version) < Gem::Version.new(Flipper::NEXT_REQUIRED_RAILS_VERSION)
+    end
+  end
+end

data/lib/flipper/errors.rb

@@ -2,26 +2,16 @@ 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.
+  # Raised when gate can not be found for an actor.
   class GateNotFound < Error
-    def initialize(thing)
-      super "Could not find gate for #{thing.inspect}"
+    def initialize(actor)
+      super "Could not find gate for #{actor.inspect}"
     end
   end
 
   # Raised when attempting to declare a group name that has already been used.
   class DuplicateGroup < Error; end
 
-  # Raised when default instance not configured but there is an attempt to
-  # use it.
-  class DefaultNotSet < Flipper::Error
-    def initialize(message = nil)
-      default = "Default flipper instance not configured. See " \
-                "Flipper.configure for how to configure the default instance."
-      super(message || default)
-    end
-  end
-
   # Raised when an invalid value is set to a configuration property
   class InvalidConfigurationValue < Flipper::Error
     def initialize(message = nil)
@@ -29,12 +19,4 @@ module Flipper
       super(message || default)
     end
   end
-
-  # Raised when accessing a configuration property that has been deprecated
-  class ConfigurationDeprecated < Flipper::Error
-    def initialize(message = nil)
-      default = "The configuration property has been deprecated"
-      super(message || default)
-    end
-  end
 end

data/lib/flipper/export.rb

@@ -0,0 +1,24 @@
+module Flipper
+  class Export
+    attr_reader :contents, :format, :version
+
+    def initialize(contents:, format: :json, version: 1)
+      @contents = contents
+      @format = format
+      @version = version
+    end
+
+    def features
+      raise NotImplementedError
+    end
+
+    def adapter
+      @adapter ||= Flipper::Adapters::Memory.new(features)
+    end
+
+    def eql?(other)
+      self.class.eql?(other.class) && @contents == other.contents && @format == other.format && @version == other.version
+    end
+    alias_method :==, :eql?
+  end
+end

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,9 @@
+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