flipper 1.3.2 → 1.4.1

data/lib/flipper/cloud/dsl.rb

@@ -10,8 +10,8 @@ module Flipper
         super Flipper.new(@cloud_configuration.adapter, instrumenter: @cloud_configuration.instrumenter)
       end
 
-      def sync
-        @cloud_configuration.sync
+      def sync(**kwargs)
+        @cloud_configuration.sync(**kwargs)
       end
 
       def sync_secret

data/lib/flipper/cloud/middleware.rb

@@ -35,7 +35,7 @@ module Flipper
             message_verifier = MessageVerifier.new(secret: flipper.sync_secret)
             if message_verifier.verify(payload, signature)
               begin
-                flipper.sync
+                flipper.sync(cache_bust: true)
                 body = JSON.generate({
                   groups: Flipper.group_names.map { |name| {name: name}}
                 })

data/lib/flipper/cloud/migrate.rb

@@ -0,0 +1,71 @@
+require "flipper/adapters/http/client"
+require "flipper/typecast"
+
+module Flipper
+  module Cloud
+    MigrateResult = Struct.new(:code, :url, :message, keyword_init: true)
+
+    DEFAULT_CLOUD_URL = "https://www.flippercloud.io".freeze
+
+    # Public: Migrate features to Flipper Cloud.
+    #
+    # flipper  - The Flipper instance to export features from (default: Flipper).
+    # app_name - Optional String name of the application.
+    #
+    # Returns a MigrateResult with code, url, and message.
+    def self.migrate(flipper = Flipper, app_name: nil)
+      export = flipper.export(format: :json, version: 1)
+      payload = {
+        export: Typecast.from_json(export.contents),
+        metadata: {app_name: app_name},
+      }
+
+      client = build_client("/api")
+      response = client.post("/migrate", Typecast.to_gzip(Typecast.to_json(payload)))
+      body = Typecast.from_json(response.body) rescue nil
+
+      MigrateResult.new(
+        code: response.code.to_i,
+        url: body&.dig("url"),
+        message: body&.dig("error"),
+      )
+    end
+
+    # Public: Push features to an existing Flipper Cloud project.
+    #
+    # token   - The String token for the Cloud environment.
+    # flipper - The Flipper instance to export features from (default: Flipper).
+    #
+    # Returns a MigrateResult with code and message.
+    def self.push(token, flipper = Flipper)
+      export = flipper.export(format: :json, version: 1)
+
+      client = build_client("/adapter", headers: {
+        "flipper-cloud-token" => token,
+      })
+      response = client.post("/import", Typecast.to_gzip(export.contents))
+      body = Typecast.from_json(response.body) rescue nil
+
+      MigrateResult.new(
+        code: response.code.to_i,
+        url: nil,
+        message: body&.dig("error"),
+      )
+    end
+
+    # Private: Build an HTTP client for Cloud API requests.
+    def self.build_client(path, headers: {})
+      base_url = ENV.fetch("FLIPPER_CLOUD_URL", DEFAULT_CLOUD_URL)
+
+      Flipper::Adapters::Http::Client.new(
+        url: "#{base_url}#{path}",
+        headers: {"content-encoding" => "gzip"}.merge(headers),
+        open_timeout: 5,
+        read_timeout: 30,
+        write_timeout: 30,
+        max_retries: 2,
+      )
+    end
+    private_class_method :build_client
+  end
+end

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

@@ -3,10 +3,10 @@ module Flipper
     class Telemetry
       class BackoffPolicy
         # Private: The default minimum timeout between intervals in milliseconds.
-        MIN_TIMEOUT_MS = 1_000
+        MIN_TIMEOUT_MS = 30_000
 
         # Private: The default maximum timeout between intervals in milliseconds.
-        MAX_TIMEOUT_MS = 30_000
+        MAX_TIMEOUT_MS = 120_000
 
         # Private: The value to multiply the current interval with for each
         # retry attempt.
@@ -67,7 +67,10 @@ module Flipper
 
           @attempts += 1
 
-          [interval, @max_timeout_ms].min
+          # cap the interval to the max timeout
+          result = [interval, @max_timeout_ms].min
+          # jitter even when maxed out
+          result == @max_timeout_ms ? add_jitter(result, 0.05) : result
         end
 
         def reset

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

@@ -34,7 +34,7 @@ module Flipper
           return if drained.empty?
           body = to_body(drained)
           return if body.nil? || body.empty?
-          retry_with_backoff(10) { submit(body) }
+          retry_with_backoff(5) { submit(body) }
         end
 
         private
@@ -51,6 +51,7 @@ module Flipper
 
           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
 
@@ -63,6 +64,7 @@ module Flipper
             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

data/lib/flipper/cloud/telemetry.rb

@@ -75,8 +75,8 @@ module Flipper
 
         @metric_storage = MetricStorage.new
 
-        @pool = Concurrent::FixedThreadPool.new(2, {
-          max_queue: 5,
+        @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,
         })
@@ -168,7 +168,7 @@ module Flipper
           end
 
           if interval = response["telemetry-interval"]
-            self.interval = interval.to_f
+            self.interval = interval
           end
         end
       rescue => error

data/lib/flipper/cloud.rb

@@ -4,6 +4,7 @@ require "flipper/middleware/memoizer"
 require "flipper/cloud/configuration"
 require "flipper/cloud/dsl"
 require "flipper/cloud/middleware"
+require "flipper/cloud/migrate"
 
 module Flipper
   module Cloud

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?, :import, :export
+    def_delegators :@adapter, :memoize=, :memoizing?, :import, :export, :adapter_stack
 
     # Public: Returns a new instance of the DSL.
     #

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/expressions/all.rb

@@ -1,5 +1,3 @@
-require "flipper/expression"
-
 module Flipper
   module Expressions
     class All

data/lib/flipper/expressions/feature_enabled.rb

@@ -0,0 +1,34 @@
+require "set"
+
+module Flipper
+  module Expressions
+    class FeatureEnabled
+      EVALUATING_KEY = :flipper_evaluating_features
+
+      def self.call(feature_name, context:)
+        evaluating = Thread.current[EVALUATING_KEY] ||= Set.new
+        feature_name = feature_name.to_s
+        current_feature = context[:feature_name].to_s
+
+        # Track the current feature so A -> B -> A is caught
+        added_current = evaluating.add?(current_feature)
+
+        begin
+          # Circular dependency: return false to break the cycle
+          return false if evaluating.include?(feature_name)
+
+          evaluating.add(feature_name)
+          actor = context[:actor]
+          if actor
+            Flipper.enabled?(feature_name, actor)
+          else
+            Flipper.enabled?(feature_name)
+          end
+        ensure
+          evaluating.delete(feature_name)
+          evaluating.delete(current_feature) if added_current
+        end
+      end
+    end
+  end
+end

data/lib/flipper/expressions/time.rb

@@ -1,8 +1,15 @@
+require "time"
+
 module Flipper
   module Expressions
     class Time
       def self.call(value)
-        ::Time.parse(value)
+        case value
+        when Numeric
+          ::Time.at(value).utc
+        else
+          ::Time.parse(value).utc
+        end
       end
     end
   end

data/lib/flipper/feature.rb

@@ -100,7 +100,14 @@ module Flipper
     #
     # Returns true if enabled, false if not.
     def enabled?(*actors)
-      actors = actors.flatten.compact.map { |actor| Types::Actor.wrap(actor) }
+      actors = Array(actors).
+        # Avoids to_ary warning that happens when passing DelegateClass of an 
+        # ActiveRecord object and using flatten here. This is tested in 
+        # spec/flipper/model/active_record_spec.rb.
+        flat_map { |actor| actor.is_a?(Array) ? actor : [actor] }. 
+        # Allows null object pattern. See PR for more. https://github.com/flippercloud/flipper/pull/887
+        reject(&:nil?). 
+        map { |actor| Types::Actor.wrap(actor) }
       actors = nil if actors.empty?
 
       # thing is left for backwards compatibility

data/lib/flipper/gate.rb

@@ -26,7 +26,7 @@ module Flipper
     # in subclass.
     #
     # Returns true if gate open for any actor, false if not.
-    def open?(actors, value, options = {})
+    def open?(context)
       false
     end
 

data/lib/flipper/gates/expression.rb

@@ -30,10 +30,10 @@ module Flipper
         expression = Flipper::Expression.build(data)
 
         if context.actors.nil? || context.actors.empty?
-          !!expression.evaluate(feature_name: context.feature_name, properties: DEFAULT_PROPERTIES)
+          !!expression.evaluate(feature_name: context.feature_name, properties: DEFAULT_PROPERTIES, actor: nil)
         else
           context.actors.any? do |actor|
-            !!expression.evaluate(feature_name: context.feature_name, properties: properties(actor))
+            !!expression.evaluate(feature_name: context.feature_name, properties: properties(actor), actor: actor)
           end
         end
       end

data/lib/flipper/instrumentation/log_subscriber.rb

@@ -53,11 +53,10 @@ module Flipper
 
         feature_name = event.payload[:feature_name]
         adapter_name = event.payload[:adapter_name]
-        gate_name = event.payload[:gate_name]
         operation = event.payload[:operation]
         result = event.payload[:result]
 
-        description = 'Flipper '
+        description = String.new('Flipper ')
         description << "feature(#{feature_name}) " unless feature_name.nil?
         description << "adapter(#{adapter_name}) "
         description << "#{operation} "

data/lib/flipper/instrumentation/statsd.rb

@@ -2,5 +2,7 @@ require 'securerandom'
 require 'active_support/notifications'
 require 'flipper/instrumentation/statsd_subscriber'
 
-ActiveSupport::Notifications.subscribe /\.flipper$/,
-                                       Flipper::Instrumentation::StatsdSubscriber
+ActiveSupport::Notifications.subscribe(
+  /\.flipper$/,
+  Flipper::Instrumentation::StatsdSubscriber
+)

data/lib/flipper/instrumentation/subscriber.rb

@@ -42,7 +42,6 @@ module Flipper
       # Private
       def update_feature_operation_metrics
         feature_name = @payload[:feature_name]
-        gate_name = @payload[:gate_name]
         operation = strip_trailing_question_mark(@payload[:operation])
         result = @payload[:result]
 
@@ -64,9 +63,6 @@ module Flipper
       def update_adapter_operation_metrics
         adapter_name = @payload[:adapter_name]
         operation = @payload[:operation]
-        result = @payload[:result]
-        value = @payload[:value]
-        key = @payload[:key]
 
         update_timer "flipper.adapter.#{adapter_name}.#{operation}"
       end

data/lib/flipper/metadata.rb

@@ -7,5 +7,6 @@ module Flipper
     "source_code_uri"   => "https://github.com/flippercloud/flipper",
     "bug_tracker_uri"   => "https://github.com/flippercloud/flipper/issues",
     "changelog_uri"     => "https://github.com/flippercloud/flipper/releases/tag/v#{Flipper::VERSION}",
+    "funding_uri"       => "https://github.com/sponsors/flippercloud",
   }.freeze
 end

data/lib/flipper/poller.rb

@@ -2,6 +2,7 @@ require 'logger'
 require 'concurrent/utility/monotonic_time'
 require 'concurrent/map'
 require 'concurrent/atomic/atomic_fixnum'
+require 'concurrent/atomic/atomic_boolean'
 
 module Flipper
   class Poller
@@ -17,7 +18,10 @@ module Flipper
     end
 
     def self.reset
-      instances.each {|_, instance| instance.stop }.clear
+      instances.each do |_, instance|
+        instance.stop
+        instance.thread&.join(1)
+      end.clear
     end
 
     MINIMUM_POLL_INTERVAL = 10
@@ -28,14 +32,12 @@ module Flipper
       @mutex = Mutex.new
       @instrumenter = options.fetch(:instrumenter, Instrumenters::Noop)
       @remote_adapter = options.fetch(:remote_adapter)
-      @interval = options.fetch(:interval, 10).to_f
       @last_synced_at = Concurrent::AtomicFixnum.new(0)
       @adapter = Adapters::Memory.new(nil, threadsafe: true)
+      @shutdown_requested = Concurrent::AtomicBoolean.new(false)
 
-      if @interval < MINIMUM_POLL_INTERVAL
-        warn "Flipper::Cloud poll interval must be greater than or equal to #{MINIMUM_POLL_INTERVAL} but was #{@interval}. Setting @interval to #{MINIMUM_POLL_INTERVAL}."
-        @interval = MINIMUM_POLL_INTERVAL
-      end
+      self.interval = options.fetch(:interval, 10)
+      @initial_interval = @interval
 
       @start_automatically = options.fetch(:start_automatically, true)
 
@@ -46,6 +48,7 @@ module Flipper
 
     def start
       reset if forked?
+      return if @shutdown_requested.true?
       ensure_worker_running
     end
 
@@ -59,10 +62,10 @@ module Flipper
     def run
       loop do
         sleep jitter
-        start = Concurrent.monotonic_time
+
         begin
           sync
-        rescue => exception
+        rescue
           # you can instrument these using poller.flipper
         end
 
@@ -72,15 +75,33 @@ module Flipper
 
     def sync
       @instrumenter.instrument("poller.#{InstrumentationNamespace}", operation: :poll) do
-        @adapter.import @remote_adapter
-        @last_synced_at.update { |time| Concurrent.monotonic_time }
+        begin
+          @adapter.import @remote_adapter
+          @last_synced_at.update { |time| Concurrent.monotonic_time }
+        ensure
+          apply_response_headers
+        end
       end
     end
 
+    # Internal: Sets the interval in seconds for how often to poll.
+    def interval=(value)
+      requested_interval = Flipper::Typecast.to_float(value)
+      new_interval = [requested_interval, MINIMUM_POLL_INTERVAL].max
+
+      if requested_interval < MINIMUM_POLL_INTERVAL
+        warn "Flipper::Cloud poll interval must be greater than or equal to #{MINIMUM_POLL_INTERVAL} but was #{requested_interval}. Setting interval to #{MINIMUM_POLL_INTERVAL}."
+      end
+
+      @interval = new_interval
+    end
+
     private
 
     def jitter
-      rand
+      # Cap jitter at 30 seconds to prevent excessive delays for large intervals
+      max_jitter = [interval * 0.1, 30].min
+      rand * max_jitter
     end
 
     def forked?
@@ -98,6 +119,7 @@ module Flipper
       begin
         return if thread_alive?
         @thread = Thread.new { run }
+        @thread&.report_on_exception = false
         @instrumenter.instrument("poller.#{InstrumentationNamespace}", {
           operation: :thread_start,
         })
@@ -112,7 +134,28 @@ module Flipper
 
     def reset
       @pid = Process.pid
+      @shutdown_requested.make_false
       mutex.unlock if mutex.locked?
     end
+
+    def apply_response_headers
+      return unless @remote_adapter.respond_to?(:last_get_all_response)
+
+      if response = @remote_adapter.last_get_all_response
+        # shutdown based on response header
+        if Flipper::Typecast.to_boolean(response["poll-shutdown"])
+          @shutdown_requested.make_true
+          @instrumenter.instrument("poller.#{InstrumentationNamespace}", {
+            operation: :shutdown_requested,
+          })
+          stop
+        end
+
+        # update interval based on response header
+        if interval = response["poll-interval"]
+          self.interval = [Flipper::Typecast.to_float(interval), @initial_interval].max
+        end
+      end
+    end
   end
 end

data/lib/flipper/version.rb

@@ -1,5 +1,5 @@
 module Flipper
-  VERSION = '1.3.2'.freeze
+  VERSION = '1.4.1'.freeze
 
   REQUIRED_RUBY_VERSION = '2.6'.freeze
   NEXT_REQUIRED_RUBY_VERSION = '3.0'.freeze

data/lib/flipper.rb

@@ -64,7 +64,7 @@ module Flipper
                  :enable_percentage_of_actors, :disable_percentage_of_actors,
                  :enable_percentage_of_time, :disable_percentage_of_time,
                  :features, :feature, :[], :preload, :preload_all,
-                 :adapter, :add, :exist?, :remove, :import, :export,
+                 :adapter, :adapter_stack, :add, :exist?, :remove, :import, :export,
                  :memoize=, :memoizing?, :read_only?,
                  :sync, :sync_secret # For Flipper::Cloud. Will error for OSS Flipper.
 
@@ -100,6 +100,22 @@ module Flipper
     Expression.build({ Random: max })
   end
 
+  def now
+    Expression.build({ Now: [] })
+  end
+
+  def time(value)
+    Expression.build({ Time: value })
+  end
+
+  def feature_enabled(name)
+    Expression.build({ FeatureEnabled: name })
+  end
+
+  def feature_disabled(name)
+    feature_enabled(name).eq(false)
+  end
+
   # Public: Use this to register a group by name.
   #
   # name - The Symbol name of the group.

data/lib/generators/flipper/setup_generator.rb

@@ -4,10 +4,15 @@ module Flipper
   module Generators
     class SetupGenerator < ::Rails::Generators::Base
       desc 'Peform any necessary steps to install Flipper'
+      source_paths << File.expand_path('templates', __dir__)
 
       class_option :token, type: :string, default: nil, aliases: '-t',
         desc: "Your personal environment token for Flipper Cloud"
 
+      def generate_initializer
+        template 'initializer.rb', 'config/initializers/flipper.rb'
+      end
+
       def generate_active_record
         invoke 'flipper:active_record' if defined?(Flipper::Adapters::ActiveRecord)
       end

data/lib/generators/flipper/templates/initializer.rb

@@ -0,0 +1,45 @@
+Rails.application.configure do
+  ## Memoization ensures that only one adapter call is made per feature per request.
+  ## For more info, see https://www.flippercloud.io/docs/optimization#memoization
+  # config.flipper.memoize = true
+
+  ## Flipper preloads all features before each request, which is recommended if:
+  ##   * you have a limited number of features (< 100?)
+  ##   * most of your requests depend on most of your features
+  ##   * you have limited gate data combined across all features (< 1k enabled gates, like individual actors, across all features)
+  ##
+  ## For more info, see https://www.flippercloud.io/docs/optimization#preloading
+  # config.flipper.preload = true
+
+  ## Warn or raise an error if an unknown feature is checked
+  ## Can be set to `:warn`, `:raise`, or `false`
+  # config.flipper.strict = Rails.env.development? && :warn
+
+  ## Show Flipper checks in logs
+  # config.flipper.log = true
+
+  ## Reconfigure Flipper to use the Memory adapter and disable Cloud in tests
+  # config.flipper.test_help = true
+
+  ## The path that Flipper Cloud will use to sync features
+  # config.flipper.cloud_path = "_flipper"
+
+  ## The instrumenter that Flipper will use. Defaults to ActiveSupport::Notifications.
+  # config.flipper.instrumenter = ActiveSupport::Notifications
+end
+
+Flipper.configure do |config|
+  ## Configure other adapters that you want to use here:
+  ## See http://flippercloud.io/docs/adapters
+  # config.use Flipper::Adapters::ActiveSupportCacheStore, Rails.cache, expires_in: 5.minutes
+end
+
+## Register a group that can be used for enabling features.
+##
+##   Flipper.enable_group :my_feature, :admins
+##
+## See https://www.flippercloud.io/docs/features#enablement-group
+#
+# Flipper.register(:admins) do |actor|
+#  actor.respond_to?(:admin?) && actor.admin?
+# end

data/spec/flipper/adapter_spec.rb

@@ -143,4 +143,24 @@ RSpec.describe Flipper::Adapter do
       expect(export.features.dig("search", :boolean)).to eq("true")
     end
   end
+
+  describe "#adapter_stack" do
+    it "returns the adapter name for a simple adapter" do
+      adapter = Flipper::Adapters::Memory.new
+      expect(adapter.adapter_stack).to eq("memory")
+    end
+
+    it "returns the chain for wrapped adapters" do
+      memory = Flipper::Adapters::Memory.new
+      memoizable = Flipper::Adapters::Memoizable.new(memory)
+      expect(memoizable.adapter_stack).to eq("memoizable -> memory")
+    end
+
+    it "returns the chain for deeply nested adapters" do
+      memory = Flipper::Adapters::Memory.new
+      strict = Flipper::Adapters::Strict.new(memory)
+      memoizable = Flipper::Adapters::Memoizable.new(strict)
+      expect(memoizable.adapter_stack).to eq("memoizable -> strict -> memory")
+    end
+  end
 end

data/spec/flipper/adapters/actor_limit_spec.rb

@@ -15,6 +15,61 @@ RSpec.describe Flipper::Adapters::ActorLimit do
           feature.enable Flipper::Actor.new("User;6")
         }.to raise_error(Flipper::Adapters::ActorLimit::LimitExceeded)
       end
+
+      it "allows exceeding limit when in sync mode" do
+        5.times { |i| feature.enable Flipper::Actor.new("User;#{i}") }
+
+        described_class.with_sync_mode do
+          expect {
+            feature.enable Flipper::Actor.new("User;6")
+          }.not_to raise_error
+        end
+      end
+    end
+  end
+
+  describe '.sync_mode' do
+    after do
+      described_class.sync_mode = nil
+    end
+
+    it 'defaults to nil/falsy' do
+      expect(described_class.sync_mode).to be_falsy
+    end
+
+    it 'can be set and read' do
+      described_class.sync_mode = true
+      expect(described_class.sync_mode).to be true
+    end
+  end
+
+  describe '.with_sync_mode' do
+    after do
+      described_class.sync_mode = nil
+    end
+
+    it 'sets sync_mode to true within block' do
+      described_class.with_sync_mode do
+        expect(described_class.sync_mode).to be true
+      end
+    end
+
+    it 'restores previous value after block' do
+      expect(described_class.sync_mode).to be_falsy
+      described_class.with_sync_mode { }
+      expect(described_class.sync_mode).to be_falsy
+    end
+
+    it 'restores previous value even on exception' do
+      expect {
+        described_class.with_sync_mode { raise "boom" }
+      }.to raise_error("boom")
+      expect(described_class.sync_mode).to be_falsy
+    end
+
+    it 'returns the block result' do
+      result = described_class.with_sync_mode { 42 }
+      expect(result).to eq(42)
     end
   end
 end