flipper 1.0.0 → 1.3.6

data/lib/flipper/cloud/telemetry/metric_storage.rb

@@ -0,0 +1,30 @@
+require 'concurrent/map'
+require 'concurrent/atomic/atomic_fixnum'
+
+module Flipper
+  module Cloud
+    class Telemetry
+      class MetricStorage
+        def initialize
+          @storage = Concurrent::Map.new { |h, k| h[k] = Concurrent::AtomicFixnum.new(0) }
+        end
+
+        def increment(metric)
+          @storage[metric].increment
+        end
+
+        def drain
+          metrics = {}
+          @storage.keys.each do |metric|
+            metrics[metric] = @storage.delete(metric).value
+          end
+          metrics.freeze
+        end
+
+        def empty?
+          @storage.empty?
+        end
+      end
+    end
+  end
+end

data/lib/flipper/cloud/telemetry/submitter.rb

@@ -0,0 +1,100 @@
+require "securerandom"
+require "flipper/typecast"
+require "flipper/cloud/telemetry/backoff_policy"
+
+module Flipper
+  module Cloud
+    class Telemetry
+      class Submitter
+        PATH = "/telemetry".freeze
+        SCHEMA_VERSION = "V1".freeze
+        GZIP_ENCODING = "gzip".freeze
+
+        Error = Class.new(StandardError) do
+          attr_reader :request_id, :response
+
+          def initialize(request_id, response)
+            @request_id = request_id
+            @response = response
+            super "Unexpected response code=#{response.code} request_id=#{request_id}"
+          end
+        end
+
+        attr_reader :cloud_configuration, :request_id, :backoff_policy
+
+        def initialize(cloud_configuration, backoff_policy: nil)
+          @cloud_configuration = cloud_configuration
+          @backoff_policy = backoff_policy || BackoffPolicy.new
+          @request_id = SecureRandom.uuid
+        end
+
+        # Returns Array of [response, error]. response and error could be nil
+        # but usually one or the other will be present.
+        def call(drained)
+          return if drained.empty?
+          body = to_body(drained)
+          return if body.nil? || body.empty?
+          retry_with_backoff(5) { submit(body) }
+        end
+
+        private
+
+        def to_body(drained)
+          enabled_metrics = drained.map { |metric, value|
+            metric.as_json(with: {"value" => value})
+          }
+
+          json = Typecast.to_json({
+            request_id: request_id,
+            enabled_metrics: enabled_metrics,
+          })
+
+          Typecast.to_gzip(json)
+        rescue => exception
+          @cloud_configuration.instrument "telemetry_error.#{Flipper::InstrumentationNamespace}", exception: exception, request_id: request_id
+          @cloud_configuration.log "action=to_body request_id=#{request_id} error=#{exception.inspect}", level: :error
+        end
+
+        def retry_with_backoff(attempts, &block)
+          result, caught_exception = nil
+          should_retry = false
+          attempts_remaining = attempts - 1
+
+          begin
+            result, should_retry = yield
+            return [result, nil] unless should_retry
+          rescue => error
+            @cloud_configuration.instrument "telemetry_retry.#{Flipper::InstrumentationNamespace}", attempts_remaining: attempts_remaining, exception: error
+            @cloud_configuration.log "action=post_to_cloud attempts_remaining=#{attempts_remaining} error=#{error.inspect}", level: :error
+            should_retry = true
+            caught_exception = error
+          end
+
+          if should_retry && attempts_remaining > 0
+            sleep @backoff_policy.next_interval.to_f / 1000
+            retry_with_backoff attempts_remaining, &block
+          else
+            [result, caught_exception]
+          end
+        end
+
+        def submit(body)
+          client = @cloud_configuration.http_client
+          client.add_header "schema-version", SCHEMA_VERSION
+          client.add_header "content-encoding", GZIP_ENCODING
+
+          response = client.post PATH, body
+          code = response.code.to_i
+
+          # Raise error and retry for retriable status codes.
+          # FIXME: what about redirects?
+          if code < 200 || code == 429 || code >= 500
+            raise Error.new(request_id, response)
+          end
+
+          response
+        end
+      end
+    end
+  end
+end

data/lib/flipper/cloud/telemetry.rb

@@ -0,0 +1,191 @@
+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(1, {
+          max_queue: 20, # ~ 20 minutes of data at 1 minute intervals
+          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
+          if Flipper::Typecast.to_boolean(response["telemetry-shutdown"])
+            debug "action=telemetry_shutdown message=The server has requested that telemetry be shut down."
+            stop
+            return
+          end
+
+          if interval = response["telemetry-interval"]
+            self.interval = interval.to_f
+          end
+        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/cloud.rb

@@ -24,7 +24,7 @@ module Flipper
       env_key = options.fetch(:env_key, 'flipper')
       memoizer_options = options.fetch(:memoizer_options, {})
 
-      app = ->(_) { [404, { 'content-type'.freeze => 'application/json'.freeze }, ['{}'.freeze]] }
+      app = ->(_) { [404, { Rack::CONTENT_TYPE => 'application/json'.freeze }, ['{}'.freeze]] }
       builder = Rack::Builder.new
       yield builder if block_given?
       builder.use Flipper::Middleware::SetupEnv, flipper, env_key: env_key

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

@@ -1,5 +1,19 @@
 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
@@ -9,17 +23,25 @@ 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,
+        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.identifier" do
+    initializer "flipper.properties" do
       ActiveSupport.on_load(:active_record) do
-        ActiveRecord::Base.include Flipper::Identifier
+        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|
@@ -44,6 +66,15 @@ module Flipper
       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
 
@@ -56,8 +87,16 @@ module Flipper
       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/export.rb

@@ -1,5 +1,3 @@
-require "flipper/adapters/memory"
-
 module Flipper
   class Export
     attr_reader :contents, :format, :version

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