flipper 1.0.0 → 1.1.0

data/lib/flipper/cloud/telemetry.rb

@@ -0,0 +1,183 @@
+require "concurrent/map"
+require "concurrent/timer_task"
+require "concurrent/executor/fixed_thread_pool"
+require "flipper/typecast"
+require "flipper/cloud/telemetry/metric"
+require "flipper/cloud/telemetry/metric_storage"
+require "flipper/cloud/telemetry/submitter"
+
+module Flipper
+  module Cloud
+    class Telemetry
+      # Internal: Map of instances of telemetry.
+      def self.instances
+        @instances ||= Concurrent::Map.new
+      end
+      private_class_method :instances
+
+      def self.reset
+        instances.each { |_, instance| instance.stop }.clear
+      end
+
+      # Internal: Fetch an instance of telemetry once per process per url +
+      # token (aka cloud endpoint). Should only ever be one instance unless you
+      # are doing some funky stuff.
+      def self.instance_for(cloud_configuration)
+        instances.compute_if_absent(cloud_configuration.url + cloud_configuration.token) do
+          new(cloud_configuration)
+        end
+      end
+
+      # Public: The cloud configuration to use for this telemetry instance.
+      attr_reader :cloud_configuration
+
+      # Internal: Where the metrics are stored between cloud submissions.
+      attr_reader :metric_storage
+
+      # Internal: The pool of background threads that submits metrics to cloud.
+      attr_reader :pool
+
+      # Internal: The timer that triggers draining the metrics to the pool.
+      attr_reader :timer
+
+      # Internal: The interval in seconds for how often telemetry should be sent to cloud.
+      attr_reader :interval
+
+      # Internal: The timeout in seconds for how long to wait for the pool to shutdown.
+      attr_reader :shutdown_timeout
+
+      # Internal: The proc that is called to submit metrics to cloud.
+      attr_accessor :submitter
+
+      def initialize(cloud_configuration)
+        @pid = $$
+        @cloud_configuration = cloud_configuration
+        self.interval = ENV.fetch("FLIPPER_TELEMETRY_INTERVAL", 60).to_f
+        self.shutdown_timeout = ENV.fetch("FLIPPER_TELEMETRY_SHUTDOWN_TIMEOUT", 5).to_f
+        self.submitter = ->(drained) { Submitter.new(@cloud_configuration).call(drained) }
+        start
+        at_exit { stop }
+      end
+
+      # Public: Records telemetry events based on active support notifications.
+      def record(name, payload)
+        return unless name == Flipper::Feature::InstrumentationName
+        return unless payload[:operation] == :enabled?
+        detect_forking
+
+        metric = Metric.new(payload[:feature_name].to_s.freeze, payload[:result])
+        @metric_storage.increment metric
+      end
+
+      # Public: Start all the tasks and setup new metric storage.
+      def start
+        info "action=start"
+
+        @metric_storage = MetricStorage.new
+
+        @pool = Concurrent::FixedThreadPool.new(2, {
+          max_queue: 5,
+          fallback_policy: :discard,
+          name: "flipper-telemetry-post-to-cloud-pool".freeze,
+        })
+
+        @timer = Concurrent::TimerTask.execute({
+          execution_interval: interval,
+          name: "flipper-telemetry-post-to-pool-timer".freeze,
+        }) { post_to_pool }
+      end
+
+      # Public: Shuts down all the tasks and tries to flush any remaining info to Cloud.
+      def stop
+        info "action=stop"
+
+        if @timer
+          debug "action=timer_shutdown_start"
+          @timer.shutdown
+          # no need to wait long for timer, all it does is drain in memory metric
+          # storage and post to the pool of background workers
+          timer_termination_result = @timer.wait_for_termination(1)
+          @timer.kill unless timer_termination_result
+          debug "action=timer_shutdown_end result=#{timer_termination_result}"
+        end
+
+        if @pool
+          post_to_pool # one last drain
+          debug "action=pool_shutdown_start"
+          @pool.shutdown
+          pool_termination_result = @pool.wait_for_termination(@shutdown_timeout)
+          @pool.kill unless pool_termination_result
+          debug "action=pool_shutdown_end result=#{pool_termination_result}"
+        end
+      end
+
+      # Public: Restart all the tasks and reset the storage.
+      def restart
+        stop
+        start
+      end
+
+      # Internal: Sets the interval in seconds for how often telemetry should be sent to cloud.
+      def interval=(value)
+        new_interval = [Typecast.to_float(value), 10].max
+        @timer&.execution_interval = new_interval
+        @interval = new_interval
+      end
+
+      # Internal: Sets the timeout in seconds for how long to wait for the pool to shutdown.
+      def shutdown_timeout=(value)
+        new_shutdown_timeout = [Typecast.to_float(value), 0.1].max
+        @shutdown_timeout = new_shutdown_timeout
+      end
+
+      private
+
+      def detect_forking
+        if @pid != $$
+          info "action=fork_detected pid_was#{@pid} pid_is=#{$$}"
+          restart
+          @pid = $$
+        end
+      end
+
+      # Drains the metric storage and enqueues the metrics to be posted to cloud.
+      def post_to_pool
+        drained = @metric_storage.drain
+        return if drained.empty?
+        debug "action=post_to_pool metrics=#{drained.size}"
+        @pool.post { post_to_cloud(drained) }
+      rescue => error
+        error "action=post_to_pool error=#{error.inspect}"
+      end
+
+      # Posts the drained metrics to cloud.
+      def post_to_cloud(drained)
+        debug "action=post_to_cloud metrics=#{drained.size}"
+        response, error = submitter.call(drained)
+        debug "action=post_to_cloud response=#{response.inspect} body=#{response&.body.inspect} error=#{error.inspect}"
+
+        # Some of the errors are response code errors which have a response and
+        # thus may have a telemetry-interval header for us to respect.
+        response ||= error.response if error && error.respond_to?(:response)
+
+        if response && interval = response["telemetry-interval"]
+          self.interval = interval.to_f
+        end
+      rescue => error
+        error "action=post_to_cloud error=#{error.inspect}"
+      end
+
+      def error(message)
+        @cloud_configuration.log message, level: :error
+      end
+
+      def info(message)
+        @cloud_configuration.log message, level: :info
+      end
+
+      def debug(message)
+        @cloud_configuration.log message
+      end
+    end
+  end
+end

data/lib/flipper/configuration.rb

@@ -1,8 +1,8 @@
 module Flipper
   class Configuration
     def initialize(options = {})
-      @default = -> { Flipper.new(adapter) }
-      @adapter = -> { Flipper::Adapters::Memory.new }
+      @builder = AdapterBuilder.new { store Flipper::Adapters::Memory }
+      @default = -> { Flipper.new(@builder.to_adapter) }
     end
 
     # The default adapter to use.
@@ -24,9 +24,20 @@ module Flipper
     #
     def adapter(&block)
       if block_given?
-        @adapter = block
+        @builder.store(block)
       else
-        @adapter.call
+        @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
 
@@ -54,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

@@ -46,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.
@@ -100,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.
@@ -219,6 +256,15 @@ module Flipper
       Flipper.group(name)
     end
 
+    # Public: Gets the expression for the feature.
+    #
+    # name - The String or Symbol name of the feature.
+    #
+    # Returns an instance of Flipper::Expression.
+    def expression(name)
+      feature(name).expression
+    end
+
     # Public: Returns a Set of the known features for this adapter.
     #
     # Returns Set of Flipper::Feature instances.
@@ -226,6 +272,11 @@ module Flipper
       adapter.features.map { |name| feature(name) }.to_set
     end
 
+    # 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

data/lib/flipper/engine.rb

@@ -9,20 +9,31 @@ module Flipper
         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"
+        cloud_path: "_flipper",
+        strict: default_strict_value
       )
     end
 
-    initializer "flipper.identifier" do
+    initializer "flipper.properties" do
+      require "flipper/model/active_record"
+
       ActiveSupport.on_load(:active_record) do
-        ActiveRecord::Base.include Flipper::Identifier
+        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|
+        if app.config.flipper.strict
+          config.use Flipper::Adapters::Strict, app.config.flipper.strict
+        end
+
         config.default do
           if cloud?
             Flipper::Cloud.new(
@@ -59,5 +70,19 @@ module Flipper
     def cloud?
       !!ENV["FLIPPER_CLOUD_TOKEN"]
     end
+
+    def 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 for now. Future versions will default to :raise in development and test
+        :warn
+      end
+    end
   end
 end

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

@@ -18,7 +18,7 @@ module Flipper
         # Public: The features hash identical to calling get_all on adapter.
         def features
           @features ||= begin
-            features = JSON.parse(contents).fetch("features")
+            features = Typecast.from_json(contents).fetch("features")
             Typecast.features_hash(features)
           rescue JSON::ParserError
             raise JsonError

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

@@ -20,7 +20,7 @@ module Flipper
             end
           end
 
-          json = JSON.dump({
+          json = Typecast.to_json({
             version: VERSION,
             features: features,
           })

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