flipper 0.24.1 → 1.3.0

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

@@ -0,0 +1,98 @@
+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(10) { 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.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.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(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
+          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

@@ -0,0 +1,53 @@
+require "flipper"
+require "flipper/middleware/setup_env"
+require "flipper/middleware/memoizer"
+require "flipper/cloud/configuration"
+require "flipper/cloud/dsl"
+require "flipper/cloud/middleware"
+
+module Flipper
+  module Cloud
+    # Public: Returns a new Flipper instance with an http adapter correctly
+    # configured for flipper cloud.
+    #
+    # token - The String token for the environment from the website.
+    # options - The Hash of options. See Flipper::Cloud::Configuration.
+    # block - The block that configuration will be yielded to allowing you to
+    #         customize this cloud instance and its adapter.
+    def self.new(options = {})
+      configuration = Configuration.new(options)
+      yield configuration if block_given?
+      DSL.new(configuration)
+    end
+
+    def self.app(flipper = nil, options = {})
+      env_key = options.fetch(:env_key, 'flipper')
+      memoizer_options = options.fetch(:memoizer_options, {})
+
+      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
+      builder.use Flipper::Middleware::Memoizer, memoizer_options.merge(env_key: env_key)
+      builder.use Flipper::Cloud::Middleware, env_key: env_key
+      builder.run app
+      klass = self
+      app = builder.to_app
+      app.define_singleton_method(:inspect) { klass.inspect } # pretty rake routes output
+      app
+    end
+
+    # Private: Configure Flipper to use Cloud by default
+    def self.set_default
+      if ENV["FLIPPER_CLOUD_TOKEN"]
+        Flipper.configure do |config|
+          config.default do
+            self.new(local_adapter: config.adapter)
+          end
+        end
+      end
+    end
+  end
+end
+
+Flipper::Cloud.set_default

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

@@ -10,7 +10,7 @@ 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
 
     # Public: Returns a new instance of the DSL.
     #
@@ -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.
@@ -210,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.
@@ -235,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.
+    # Public: Gets the expression for the feature.
     #
-    # 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.
-    #
-    # 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.
     #
@@ -272,8 +272,9 @@ 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.

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,25 +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)
-      warn "Flipper::DefaultNotSet is deprecated and will be removed in 1.0"
-      super
-    end
-  end
-
   # Raised when an invalid value is set to a configuration property
   class InvalidConfigurationValue < Flipper::Error
     def initialize(message = nil)
@@ -28,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,26 @@
+require "flipper/adapters/memory"
+
+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