flipper 1.0.0 → 1.1.0

data/lib/flipper/cloud/configuration.rb

@@ -1,3 +1,4 @@
+require "logger"
 require "socket"
 require "flipper/adapters/http"
 require "flipper/adapters/poll"
@@ -5,8 +6,9 @@ require "flipper/poller"
 require "flipper/adapters/memory"
 require "flipper/adapters/dual_write"
 require "flipper/adapters/sync/synchronizer"
-require "flipper/cloud/instrumenter"
-require "brow"
+require "flipper/cloud/telemetry"
+require "flipper/cloud/telemetry/instrumenter"
+require "flipper/cloud/telemetry/submitter"
 
 module Flipper
   module Cloud
@@ -19,18 +21,13 @@ module Flipper
 
       DEFAULT_URL = "https://www.flippercloud.io/adapter".freeze
 
-      # Private: Keeps track of brow instances so they can be shared across
-      # threads.
-      def self.brow_instances
-        @brow_instances ||= Concurrent::Map.new
-      end
-
       # Public: The token corresponding to an environment on flippercloud.io.
       attr_accessor :token
 
       # Public: The url for http adapter. Really should only be customized for
-       #        development work. Feel free to forget you ever saw this.
-      attr_reader :url
+      #         development work if you are me and you are not me. Feel free to
+      #         forget you ever saw this.
+      attr_accessor :url
 
       # Public: net/http read timeout for all http requests (default: 5).
       attr_accessor :read_timeout
@@ -73,32 +70,25 @@ module Flipper
       # occur or not.
       attr_accessor :sync_secret
 
-      def initialize(options = {})
-        @token = options.fetch(:token) { ENV["FLIPPER_CLOUD_TOKEN"] }
+      # Public: The logger to use for debugging inner workings.
+      attr_accessor :logger
 
-        if @token.nil?
-          raise ArgumentError, "Flipper::Cloud token is missing. Please set FLIPPER_CLOUD_TOKEN or provide the token (e.g. Flipper::Cloud.new(token: 'token'))."
-        end
+      # Public: Should the logger log or not (default: true).
+      attr_accessor :logging_enabled
 
-        @read_timeout = options.fetch(:read_timeout) { ENV.fetch("FLIPPER_CLOUD_READ_TIMEOUT", 5).to_f }
-        @open_timeout = options.fetch(:open_timeout) { ENV.fetch("FLIPPER_CLOUD_OPEN_TIMEOUT", 5).to_f }
-        @write_timeout = options.fetch(:write_timeout) { ENV.fetch("FLIPPER_CLOUD_WRITE_TIMEOUT", 5).to_f }
-        @sync_interval = options.fetch(:sync_interval) { ENV.fetch("FLIPPER_CLOUD_SYNC_INTERVAL", 10).to_f }
-        @sync_secret = options.fetch(:sync_secret) { ENV["FLIPPER_CLOUD_SYNC_SECRET"] }
-        @local_adapter = options.fetch(:local_adapter) { Adapters::Memory.new }
-        @debug_output = options[:debug_output]
-        @adapter_block = ->(adapter) { adapter }
-        self.url = options.fetch(:url) { ENV.fetch("FLIPPER_CLOUD_URL", DEFAULT_URL) }
+      # Public: The telemetry instance to use for tracking feature usage.
+      attr_accessor :telemetry
 
-        instrumenter = options.fetch(:instrumenter, Instrumenters::Noop)
+      # Public: Should telemetry be enabled or not (default: false).
+      attr_accessor :telemetry_enabled
 
-        # This is alpha. Don't use this unless you are me. And you are not me.
-        cloud_instrument = options.fetch(:cloud_instrument) { ENV["FLIPPER_CLOUD_INSTRUMENT"] == "1" }
-        @instrumenter = if cloud_instrument
-          Instrumenter.new(brow: brow, instrumenter: instrumenter)
-        else
-          instrumenter
-        end
+      def initialize(options = {})
+        setup_auth options
+        setup_log options
+        setup_http options
+        setup_sync options
+        setup_adapter options
+        setup_telemetry options
       end
 
       # Public: Read or customize the http adapter. Calling without a block will
@@ -120,38 +110,31 @@ module Flipper
         end
       end
 
-      # Public: Set url for the http adapter.
-      attr_writer :url
-
+      # Public: Force a sync.
       def sync
         Flipper::Adapters::Sync::Synchronizer.new(local_adapter, http_adapter, {
           instrumenter: instrumenter,
         }).call
       end
 
-      def brow
-        self.class.brow_instances.compute_if_absent(url + token) do
-          uri = URI.parse(url)
-          uri.path = "#{uri.path}/events".squeeze("/")
-
-          Brow::Client.new({
-            url: uri.to_s,
-            headers: {
-              "Accept" => "application/json",
-              "Content-Type" => "application/json",
-              "User-Agent" => "Flipper v#{VERSION} via Brow v#{Brow::VERSION}",
-              "Flipper-Cloud-Token" => @token,
-            }
-          })
-        end
-      end
-
       # Public: The method that will be used to synchronize local adapter with
       # cloud. (default: :poll, will be :webhook if sync_secret is set).
       def sync_method
         sync_secret ? :webhook : :poll
       end
 
+      # Internal: The http client used by the http adapter. Exposed so we can
+      # use the same client for posting telemetry.
+      def http_client
+        http_adapter.client
+      end
+
+      # Internal: Logs message if logging is enabled.
+      def log(message, level: :debug)
+        return unless logging_enabled
+        logger.send(level, "name=flipper_cloud #{message}")
+      end
+
       private
 
       def app_adapter
@@ -184,6 +167,92 @@ module Flipper
           },
         })
       end
+
+      def setup_auth(options)
+        set_option :token, options, required: true
+      end
+
+      def setup_log(options)
+        set_option :logging_enabled, options, default: true, typecast: :boolean
+        set_option :logger, options, from_env: false, default: -> {
+          if logging_enabled
+            Logger.new(STDOUT)
+          else
+            Logger.new("/dev/null")
+          end
+        }
+      end
+
+      def setup_http(options)
+        set_option :url, options, default: DEFAULT_URL
+        set_option :debug_output, options, from_env: false
+        set_option :read_timeout, options, default: 5, typecast: :float, minimum: 0.1
+        set_option :open_timeout, options, default: 2, typecast: :float, minimum: 0.1
+        set_option :write_timeout, options, default: 5, typecast: :float, minimum: 0.1
+      end
+
+      def setup_sync(options)
+        set_option :sync_interval, options, default: 10, typecast: :float, minimum: 10
+        set_option :sync_secret, options
+      end
+
+      def setup_adapter(options)
+        set_option :local_adapter, options, default: -> { Adapters::Memory.new }, from_env: false
+        @adapter_block = ->(adapter) { adapter }
+      end
+
+      def setup_telemetry(options)
+        # Needs to be after url and token assignments because they are used for
+        # uniqueness in Telemetry.instance_for.
+        set_option :telemetry, options, from_env: false, default: -> {
+          Telemetry.instance_for(self)
+        }
+
+        # This is alpha. Don't use this unless you are me. And you are not me.
+        set_option :telemetry_enabled, options, default: false, typecast: :boolean
+        instrumenter = options.fetch(:instrumenter, Instrumenters::Noop)
+        @instrumenter = if telemetry_enabled
+          Telemetry::Instrumenter.new(self, instrumenter)
+        else
+          instrumenter
+        end
+      end
+
+      # Internal: Super helper for defining an option that can be set via
+      # options hash or ENV with defaults, typecasting and minimums.
+      def set_option(name, options, default: nil, typecast: nil, minimum: nil, from_env: true, required: false)
+        env_var = "FLIPPER_CLOUD_#{name.to_s.upcase}"
+        value = options.fetch(name) {
+          default_value = default.respond_to?(:call) ? default.call : default
+          if from_env
+            ENV.fetch(env_var, default_value)
+          else
+            default_value
+          end
+        }
+        value = Flipper::Typecast.send("to_#{typecast}", value) if typecast
+        send("#{name}=", value)
+        enforce_minimum(name, minimum) if minimum
+
+        if required
+          option_value = send(name)
+          if option_value.nil? || option_value.empty?
+            message = "Flipper::Cloud #{name} is missing. Please "
+            message << "set #{env_var} or " if from_env
+            message << "provide #{name} (e.g. Flipper::Cloud.new(#{name}: value))."
+            raise ArgumentError, message
+          end
+        end
+      end
+
+      # Enforce minimum interval for tasks that run on a timer.
+      def enforce_minimum(name, minimum)
+        provided = send(name)
+        if provided && provided < minimum
+          warn "Flipper::Cloud##{name} must be at least #{minimum} seconds but was #{provided}. Using #{minimum} seconds."
+          send(:instance_variable_set, "@#{name}", minimum)
+        end
+      end
     end
   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