flipper 0.16.0 → 1.4.0

data/lib/flipper/cli.rb

@@ -0,0 +1,314 @@
+require 'optparse'
+
+module Flipper
+  class CLI < OptionParser
+    def self.run(argv = ARGV)
+      new.run(argv)
+    end
+
+    # Path to the local Rails application's environment configuration.
+    DEFAULT_REQUIRE = "./config/environment"
+
+    attr_accessor :shell
+
+    def initialize(stdout: $stdout, stderr: $stderr, shell: Bundler::Thor::Base.shell.new)
+      super
+
+      # Program is always flipper, no matter how it's invoked
+      @program_name = 'flipper'
+      @require = ENV.fetch("FLIPPER_REQUIRE", DEFAULT_REQUIRE)
+      @commands = {}
+
+      # Extend whatever shell to support output redirection
+      @shell = shell.extend(ShellOutput)
+      shell.redirect(stdout: stdout, stderr: stderr)
+
+      %w[enable disable].each do |action|
+        command action do |c|
+          c.banner = "Usage: #{c.program_name} [options] <feature>"
+          c.description = "#{action.to_s.capitalize} a feature"
+
+          values = []
+
+          c.on('-a id', '--actor=id', "#{action} for an actor") do |id|
+            values << Actor.new(id)
+          end
+          c.on('-g name', '--group=name', "#{action} for a group") do |name|
+            values << Types::Group.new(name)
+          end
+          c.on('-p NUM', '--percentage-of-actors=NUM', Numeric, "#{action} for a percentage of actors") do |num|
+            values << Types::PercentageOfActors.new(num)
+          end
+          c.on('-t NUM', '--percentage-of-time=NUM', Numeric, "#{action} for a percentage of time") do |num|
+            values << Types::PercentageOfTime.new(num)
+          end
+          c.on('-x expressions', '--expression=NUM', "#{action} for the given expression") do |expression|
+            begin
+              values << Flipper::Expression.build(JSON.parse(expression))
+            rescue JSON::ParserError => e
+              ui.error "JSON parse error #{e.message}"
+              ui.trace(e)
+              exit 1
+            rescue ArgumentError => e
+              ui.error "Invalid expression: #{e.message}"
+              ui.trace(e)
+              exit 1
+            end
+          end
+
+          c.action do |feature|
+            f = Flipper.feature(feature)
+
+            if values.empty?
+              f.send(action)
+            else
+              values.each { |value| f.send(action, value) }
+            end
+
+            ui.info feature_details(f)
+          end
+        end
+      end
+
+      command 'list' do |c|
+        c.description = "List defined features"
+        c.action do
+          ui.info feature_summary(Flipper.features)
+        end
+      end
+
+      command 'show' do |c|
+        c.description = "Show a defined feature"
+        c.action do |feature|
+          ui.info feature_details(Flipper.feature(feature))
+        end
+      end
+
+      command 'export' do |c|
+        c.description = "Export features as JSON"
+        c.action do
+          export = Flipper.export(format: :json, version: 1)
+          ui.info export.contents
+        end
+      end
+
+      command 'cloud' do |c|
+        c.description = "Flipper Cloud commands"
+        c.action do |subcommand = nil, *args|
+          require 'flipper/cloud/migrate'
+
+          case subcommand
+          when 'migrate'
+            result = Flipper::Cloud.migrate(Flipper)
+            if result.url
+              ui.info "Migrating to Flipper Cloud..."
+              ui.info result.url
+              system("open", result.url)
+            else
+              message = "Migration failed (HTTP #{result.code})"
+              message << ": #{result.message}" if result.message
+              ui.error message
+              exit 1
+            end
+          when 'push'
+            token = args.first
+            unless token
+              ui.error "Usage: flipper cloud push <token>"
+              exit 1
+            end
+            result = Flipper::Cloud.push(token, Flipper)
+            if result.code == 204
+              ui.info "Successfully pushed features to Flipper Cloud"
+            else
+              message = "Push failed (HTTP #{result.code})"
+              message << ": #{result.message}" if result.message
+              ui.error message
+              exit 1
+            end
+          else
+            ui.info "Usage: flipper cloud <command>"
+            ui.info ""
+            ui.info "Commands:"
+            ui.info "  migrate  Migrate features to a new Flipper Cloud account"
+            ui.info "  push     Push features to an existing Flipper Cloud project"
+          end
+        end
+      end
+
+      command 'help' do |c|
+        c.load_environment = false
+        c.action do |command = nil|
+          ui.info command ? @commands[command].help : help
+        end
+      end
+
+      on_tail('-r path', "The path to load your application. Default: #{@require}") do |path|
+        @require = path
+      end
+
+      # Options available on all commands
+      on_tail('-h', '--help', 'Print help message') do
+        ui.info help
+        exit
+      end
+
+      # Set help documentation
+      self.banner = "Usage: #{program_name} [options] <command>"
+      separator ""
+      separator "Commands:"
+
+      pad = @commands.keys.map(&:length).max + 2
+      @commands.each do |name, command|
+        separator "  #{name.to_s.ljust(pad, " ")} #{command.description}" if command.description
+      end
+
+      separator ""
+      separator "Options:"
+    end
+
+    def run(argv)
+      command, *args = order(argv)
+
+      if @commands[command]
+        load_environment! if @commands[command].load_environment
+        @commands[command].run(args)
+      else
+        ui.info help
+
+        if command
+          ui.error "Unknown command: #{command}"
+          exit 1
+        end
+      end
+    rescue OptionParser::InvalidOption => e
+      ui.error e.message
+      exit 1
+    end
+
+    # Helper method to define a new command
+    def command(name, &block)
+      @commands[name] = Command.new(program_name: "#{program_name} #{name}")
+      block.call(@commands[name])
+    end
+
+    def load_environment!
+      ENV["FLIPPER_CLOUD_LOGGING_ENABLED"] ||= "false"
+      require File.expand_path(@require)
+      # Ensure all of flipper gets loaded if it hasn't already.
+      require 'flipper'
+    rescue LoadError => e
+      ui.error e.message
+      exit 1
+    end
+
+    def feature_summary(features)
+      features = Array(features)
+      padding = features.map { |f| f.key.to_s.length }.max
+
+      features.map do |feature|
+        summary = case feature.state
+        when :on
+          colorize("⏺ enabled", [:GREEN])
+        when :off
+          "⦸ disabled"
+        else
+            "#{colorize("◯ enabled", [:YELLOW])} for " + feature.enabled_gates.map do |gate|
+            case gate.name
+            when :actor
+              pluralize feature.actors_value.size, 'actor', 'actors'
+            when :group
+              pluralize feature.groups_value.size, 'group', 'groups'
+            when :percentage_of_actors
+              "#{feature.percentage_of_actors_value}% of actors"
+            when :percentage_of_time
+              "#{feature.percentage_of_time_value}% of time"
+            when :expression
+              "an expression"
+            end
+          end.join(', ')
+        end
+
+        colorize("%-#{padding}s" % feature.key, [:BOLD, :WHITE]) + " is #{summary}"
+      end.join("\n")
+    end
+
+    def feature_details(feature)
+      summary = case feature.state
+      when :on
+        colorize("⏺ enabled", [:GREEN])
+      when :off
+        "⦸ disabled"
+      else
+        lines = feature.enabled_gates.map do |gate|
+          case gate.name
+          when :actor
+            [ pluralize(feature.actors_value.size, 'actor', 'actors') ] +
+            feature.actors_value.map { |actor| "- #{actor}" }
+          when :group
+            [ pluralize(feature.groups_value.size, 'group', 'groups') ] +
+            feature.groups_value.map { |group| "  - #{group}" }
+          when :percentage_of_actors
+            "#{feature.percentage_of_actors_value}% of actors"
+          when :percentage_of_time
+            "#{feature.percentage_of_time_value}% of time"
+          when :expression
+            json = indent(JSON.pretty_generate(feature.expression_value), 2)
+            "the expression: \n#{colorize(json, [:MAGENTA])}"
+          end
+        end
+
+        "#{colorize("◯ conditionally enabled", [:YELLOW])} for:\n" +
+        indent(lines.flatten.join("\n"), 2)
+      end
+
+      "#{colorize(feature.key, [:BOLD, :WHITE])} is #{summary}"
+    end
+
+    def pluralize(count, singular, plural)
+      "#{count} #{count == 1 ? singular : plural}"
+    end
+
+    def colorize(text, colors)
+      ui.add_color(text, *colors)
+    end
+
+    def ui
+      @ui ||= Bundler::UI::Shell.new.tap do |ui|
+        ui.shell = shell
+      end
+    end
+
+    def indent(text, spaces)
+      text.gsub(/^/, " " * spaces)
+    end
+
+    # Redirect the shell's output to the given stdout and stderr streams
+    module ShellOutput
+      attr_reader :stdout, :stderr
+
+      def redirect(stdout: $stdout, stderr: $stderr)
+        @stdout, @stderr = stdout, stderr
+      end
+    end
+
+    class Command < OptionParser
+      attr_accessor :description, :load_environment
+
+      def initialize(program_name: nil)
+        super()
+        @program_name = program_name
+        @load_environment = true
+        @action = lambda { }
+      end
+
+      def run(argv)
+        # Parse argv and call action with arguments
+        @action.call(*permute(argv))
+      end
+
+      def action(&block)
+        @action = block
+      end
+    end
+  end
+end

data/lib/flipper/cloud/configuration.rb

@@ -0,0 +1,271 @@
+require "logger"
+require "socket"
+require "flipper/adapters/http"
+require "flipper/adapters/poll"
+require "flipper/poller"
+require "flipper/adapters/dual_write"
+require "flipper/adapters/sync/synchronizer"
+require "flipper/cloud/telemetry"
+require "flipper/cloud/telemetry/instrumenter"
+require "flipper/cloud/telemetry/submitter"
+
+module Flipper
+  module Cloud
+    class Configuration
+      # The set of valid ways that syncing can happpen.
+      VALID_SYNC_METHODS = Set[
+        :poll,
+        :webhook,
+      ].freeze
+
+      DEFAULT_URL = "https://www.flippercloud.io/adapter".freeze
+
+      # 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 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
+
+      # Public: net/http open timeout for all http requests (default: 5).
+      attr_accessor :open_timeout
+
+      # Public: net/http write timeout for all http requests (default: 5).
+      attr_accessor :write_timeout
+
+      # Public: IO stream to send debug output too. Off by default.
+      #
+      #  # for example, this would send all http request information to STDOUT
+      #  configuration = Flipper::Cloud::Configuration.new
+      #  configuration.debug_output = STDOUT
+      attr_accessor :debug_output
+
+      # Public: Instrumenter to use for the Flipper instance returned by
+      #         Flipper::Cloud.new (default: Flipper::Instrumenters::Noop).
+      #
+      #  # for example, to use active support notifications you could do:
+      #  configuration = Flipper::Cloud::Configuration.new
+      #  configuration.instrumenter = ActiveSupport::Notifications
+      attr_accessor :instrumenter
+
+      # Public: Local adapter that all reads should go to in order to ensure
+      # latency is low and resiliency is high. This adapter is automatically
+      # kept in sync with cloud.
+      #
+      #  # for example, to use active record you could do:
+      #  configuration = Flipper::Cloud::Configuration.new
+      #  configuration.local_adapter = Flipper::Adapters::ActiveRecord.new
+      attr_accessor :local_adapter
+
+      # Public: The Integer or Float number of seconds between attempts to bring
+      # the local in sync with cloud (default: 10).
+      attr_accessor :sync_interval
+
+      # Public: The secret used to verify if syncs in the middleware should
+      # occur or not.
+      attr_accessor :sync_secret
+
+      # Public: The logger to use for debugging inner workings.
+      attr_accessor :logger
+
+      # Public: Should the logger log or not (default: true).
+      attr_accessor :logging_enabled
+
+      # Public: The telemetry instance to use for tracking feature usage.
+      attr_accessor :telemetry
+
+      # Public: Should telemetry be enabled or not (default: false).
+      attr_accessor :telemetry_enabled
+
+      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
+      # perform a read. Calling with a block yields the cloud adapter
+      # for customization.
+      #
+      #   # for example, to instrument the http calls, you can wrap the http
+      #   # adapter with the intsrumented adapter
+      #   configuration = Flipper::Cloud::Configuration.new
+      #   configuration.adapter do |adapter|
+      #     Flipper::Adapters::Instrumented.new(adapter)
+      #   end
+      #
+      def adapter(&block)
+        if block_given?
+          @adapter_block = block
+        else
+          @adapter_block.call app_adapter
+        end
+      end
+
+      # Public: Force a sync.
+      def sync(cache_bust: false)
+        Flipper::Adapters::Sync::Synchronizer.new(local_adapter, http_adapter, {
+          instrumenter: instrumenter,
+          cache_bust: cache_bust,
+        }).call
+      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
+
+      def instrument(name, payload = {}, &block)
+        instrumenter.instrument(name, payload, &block)
+      end
+
+      private
+
+      def app_adapter
+        Flipper::Adapters::DualWrite.new(poll_adapter, http_adapter)
+      end
+
+      def poller
+        Flipper::Poller.get(@url + @token, {
+          interval: sync_interval,
+          remote_adapter: http_adapter,
+          instrumenter: instrumenter,
+        }).tap(&:start)
+      end
+
+      def poll_adapter
+        Flipper::Adapters::Poll.new(poller, local_adapter)
+      end
+
+      def http_adapter
+        Flipper::Adapters::Http.new({
+          url: @url,
+          read_timeout: @read_timeout,
+          open_timeout: @open_timeout,
+          write_timeout: @write_timeout,
+          max_retries: 0, # we'll handle retries ourselves
+          debug_output: @debug_output,
+          headers: {
+            "flipper-cloud-token" => @token,
+            "accept-encoding" => "gzip",
+          },
+        })
+      end
+
+      def setup_auth(options)
+        set_option :token, options, required: true
+      end
+
+      def setup_log(options)
+        set_option :logging_enabled, options, default: false, 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
+
+        if @debug_output.nil? && Flipper::Typecast.to_boolean(ENV["FLIPPER_CLOUD_DEBUG_OUTPUT_STDOUT"])
+          @debug_output = STDOUT
+        end
+
+        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_secret, options
+
+        # 1 hour for webhook, 10 seconds for poll. If using webhooks we don't
+        # need to sync as often but we should still sync occasionally to avoid
+        # any chance of stale data.
+        default_interval = sync_method == :webhook ? 3600 : 10
+        set_option :sync_interval, options, default: default_interval, typecast: :float, minimum: 10
+      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)
+        }
+
+        set_option :telemetry_enabled, options, default: true, 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 = String.new("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/dsl.rb

@@ -0,0 +1,27 @@
+require 'forwardable'
+
+module Flipper
+  module Cloud
+    class DSL < SimpleDelegator
+      attr_reader :cloud_configuration
+
+      def initialize(cloud_configuration)
+        @cloud_configuration = cloud_configuration
+        super Flipper.new(@cloud_configuration.adapter, instrumenter: @cloud_configuration.instrumenter)
+      end
+
+      def sync(**kwargs)
+        @cloud_configuration.sync(**kwargs)
+      end
+
+      def sync_secret
+        @cloud_configuration.sync_secret
+      end
+
+      def inspect
+        inspect_id = ::Kernel::format "%x", (object_id * 2)
+        %(#<#{self.class}:0x#{inspect_id} @cloud_configuration=#{cloud_configuration.inspect}, flipper=#{__getobj__.inspect}>)
+      end
+    end
+  end
+end

data/lib/flipper/cloud/message_verifier.rb

@@ -0,0 +1,95 @@
+require "openssl"
+require "digest/sha2"
+
+module Flipper
+  module Cloud
+    class MessageVerifier
+      class InvalidSignature < StandardError; end
+
+      DEFAULT_VERSION = "v1"
+
+      def self.header(signature, timestamp, version = DEFAULT_VERSION)
+        raise ArgumentError, "timestamp should be an instance of Time" unless timestamp.is_a?(Time)
+        raise ArgumentError, "signature should be a string" unless signature.is_a?(String)
+        "t=#{timestamp.to_i},#{version}=#{signature}"
+      end
+
+      def initialize(secret:, version: DEFAULT_VERSION)
+        @secret = secret
+        @version = version || DEFAULT_VERSION
+
+        raise ArgumentError, "secret should be a string" unless @secret.is_a?(String)
+        raise ArgumentError, "version should be a string" unless @version.is_a?(String)
+      end
+
+      def generate(payload, timestamp)
+        raise ArgumentError, "timestamp should be an instance of Time" unless timestamp.is_a?(Time)
+        raise ArgumentError, "payload should be a string" unless payload.is_a?(String)
+
+        OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), @secret, "#{timestamp.to_i}.#{payload}")
+      end
+
+      def header(signature, timestamp)
+        self.class.header(signature, timestamp, @version)
+      end
+
+      # Public: Verifies the signature header for a given payload.
+      #
+      # Raises a InvalidSignature in the following cases:
+      # - the header does not match the expected format
+      # - no signatures found with the expected scheme
+      # - no signatures matching the expected signature
+      # - a tolerance is provided and the timestamp is not within the
+      #   tolerance
+      #
+      # Returns true otherwise.
+      def verify(payload, header, tolerance: nil)
+        begin
+          timestamp, signatures = get_timestamp_and_signatures(header)
+        rescue StandardError
+          raise InvalidSignature, "Unable to extract timestamp and signatures from header"
+        end
+
+        if signatures.empty?
+          raise InvalidSignature, "No signatures found with expected version #{@version}"
+        end
+
+        expected_sig = generate(payload, timestamp)
+        unless signatures.any? { |s| secure_compare(expected_sig, s) }
+          raise InvalidSignature, "No signatures found matching the expected signature for payload"
+        end
+
+        if tolerance && timestamp < Time.now - tolerance
+          raise InvalidSignature, "Timestamp outside the tolerance zone (#{Time.at(timestamp)})"
+        end
+
+        true
+      end
+
+      private
+
+      # Extracts the timestamp and the signature(s) with the desired version
+      # from the header
+      def get_timestamp_and_signatures(header)
+        list_items = header.split(/,\s*/).map { |i| i.split("=", 2) }
+        timestamp = Integer(list_items.select { |i| i[0] == "t" }[0][1])
+        signatures = list_items.select { |i| i[0] == @version }.map { |i| i[1] }
+        [Time.at(timestamp), signatures]
+      end
+
+      # Private
+      def fixed_length_secure_compare(a, b)
+        raise ArgumentError, "string length mismatch." unless a.bytesize == b.bytesize
+        l = a.unpack "C#{a.bytesize}"
+        res = 0
+        b.each_byte { |byte| res |= byte ^ l.shift }
+        res == 0
+      end
+
+      # Private
+      def secure_compare(a, b)
+        fixed_length_secure_compare(::Digest::SHA256.digest(a), ::Digest::SHA256.digest(b)) && a == b
+      end
+    end
+  end
+end