flipper 0.26.0 → 1.1.0

data/lib/flipper/cloud/routes.rb

@@ -0,0 +1,14 @@
+# Default routes loaded by Flipper::Cloud::Engine
+Rails.application.routes.draw do
+  if ENV["FLIPPER_CLOUD_TOKEN"] && ENV["FLIPPER_CLOUD_SYNC_SECRET"]
+    require 'flipper/cloud'
+    config = Rails.application.config.flipper
+
+    cloud_app = Flipper::Cloud.app(nil,
+      env_key: config.env_key,
+      memoizer_options: { preload: config.preload }
+    )
+
+    mount cloud_app, at: config.cloud_path
+  end
+end

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

@@ -0,0 +1,93 @@
+module Flipper
+  module Cloud
+    class Telemetry
+      class BackoffPolicy
+        # Private: The default minimum timeout between intervals in milliseconds.
+        MIN_TIMEOUT_MS = 1_000
+
+        # Private: The default maximum timeout between intervals in milliseconds.
+        MAX_TIMEOUT_MS = 30_000
+
+        # Private: The value to multiply the current interval with for each
+        # retry attempt.
+        MULTIPLIER = 1.5
+
+        # Private: The randomization factor to use to create a range around the
+        # retry interval.
+        RANDOMIZATION_FACTOR = 0.5
+
+        # Private
+        attr_reader :min_timeout_ms, :max_timeout_ms, :multiplier, :randomization_factor
+
+        # Private
+        attr_reader :attempts
+
+        # Public: Create new instance of backoff policy.
+        #
+        # options - The Hash of options.
+        #   :min_timeout_ms - The minimum backoff timeout.
+        #   :max_timeout_ms - The maximum backoff timeout.
+        #   :multiplier - The value to multiply the current interval with for each
+        #                 retry attempt.
+        #   :randomization_factor - The randomization factor to use to create a range
+        #                           around the retry interval.
+        def initialize(options = {})
+          @min_timeout_ms = options.fetch(:min_timeout_ms) {
+            ENV.fetch("FLIPPER_BACKOFF_MIN_TIMEOUT_MS", MIN_TIMEOUT_MS).to_i
+          }
+          @max_timeout_ms = options.fetch(:max_timeout_ms) {
+            ENV.fetch("FLIPPER_BACKOFF_MAX_TIMEOUT_MS", MAX_TIMEOUT_MS).to_i
+          }
+          @multiplier = options.fetch(:multiplier) {
+            ENV.fetch("FLIPPER_BACKOFF_MULTIPLIER", MULTIPLIER).to_f
+          }
+          @randomization_factor = options.fetch(:randomization_factor) {
+            ENV.fetch("FLIPPER_BACKOFF_RANDOMIZATION_FACTOR", RANDOMIZATION_FACTOR).to_f
+          }
+
+          unless @min_timeout_ms >= 0
+            raise ArgumentError, ":min_timeout_ms must be >= 0 but was #{@min_timeout_ms.inspect}"
+          end
+
+          unless @max_timeout_ms >= 0
+            raise ArgumentError, ":max_timeout_ms must be >= 0 but was #{@max_timeout_ms.inspect}"
+          end
+
+          unless @min_timeout_ms <= max_timeout_ms
+            raise ArgumentError, ":min_timeout_ms (#{@min_timeout_ms.inspect}) must be <= :max_timeout_ms (#{@max_timeout_ms.inspect})"
+          end
+
+          @attempts = 0
+        end
+
+        # Public: Returns the next backoff interval in milliseconds.
+        def next_interval
+          interval = @min_timeout_ms * (@multiplier**@attempts)
+          interval = add_jitter(interval, @randomization_factor)
+
+          @attempts += 1
+
+          [interval, @max_timeout_ms].min
+        end
+
+        def reset
+          @attempts = 0
+        end
+
+        private
+
+        def add_jitter(base, randomization_factor)
+          random_number = rand
+          max_deviation = base * randomization_factor
+          deviation = random_number * max_deviation
+
+          if random_number < 0.5
+            base - deviation
+          else
+            base + deviation
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+require "delegate"
+
+module Flipper
+  module Cloud
+    class Telemetry
+      class Instrumenter < SimpleDelegator
+        def initialize(cloud_configuration, instrumenter)
+          super instrumenter
+          @cloud_configuration = cloud_configuration
+        end
+
+        def instrument(name, payload = {}, &block)
+          return_value = instrumenter.instrument(name, payload, &block)
+          @cloud_configuration.telemetry.record(name, payload)
+          return_value
+        end
+
+        private
+
+        def instrumenter
+          __getobj__
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+module Flipper
+  module Cloud
+    class Telemetry
+      class Metric
+        attr_reader :key, :time, :result
+
+        def initialize(key, result, time = Time.now)
+          @key = key
+          @result = result
+          @time = time.to_i / 60 * 60
+        end
+
+        def as_json(options = {})
+          data = {
+            "key" => key.to_s,
+            "time" => time,
+            "result" => result,
+          }
+
+          if options[:with]
+            data.merge!(options[:with])
+          end
+
+          data
+        end
+
+        def eql?(other)
+          self.class.eql?(other.class) &&
+            @key == other.key && @time == other.time && @result == other.result
+        end
+        alias :== :eql?
+
+        def hash
+          [self.class, @key, @time, @result].hash
+        end
+      end
+    end
+  end
+end

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,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,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/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, { 'content-type'.freeze => '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