featureflip 2.8.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3d59e135c8bde6e1955c965c186ade207bbb58961bbb95ad949497940efbd8d
-  data.tar.gz: 9a25588388685e6e08f206b4ed623b491e949df2fc448797ba4305cdfdedfd4f
+  metadata.gz: 33b15e24100b214989443fd146e3b5a4ef29c92ee28f457419c4ef0816e01efa
+  data.tar.gz: f638de9e949664b629c35771bce31f2dff71eb018133eeecc3a1d952ba037992
 SHA512:
-  metadata.gz: ad445faee786f603e3702df154e78afe5ae8d3ca6868be6c4d5dcc97f03fc4006f364cf40d9c2a73d5e0d43744f5074228186b6b3f69a1a97fd03ca678aa037a
-  data.tar.gz: 5bdd2687ecec69386d9cde9f8b0c5190bd4bee4e49f3187f3762263be21e28e6d3dd09517c4b44451f4ddcc969fa70543a7177f91ba6f2b39fd7a785bf590147
+  metadata.gz: 0c3da771ddf9cb78f4a73f890d03d178047f78dfdf0a1347a52ca82dd1e3721f79b3249856ea1413068aa924b1f5d9acf9a8c2449b79731134508b9f4701714f
+  data.tar.gz: f73db84108ad650e6812868b217fc3b981ba0cdbc2985de312ef94d2fc88d8fdb2d24cc638a5c24837b3598271f7a49005ed5ba1b9f428778099909042b5457b

data/lib/featureflip/client.rb

@@ -2,6 +2,9 @@ module Featureflip
   class Client
     private_class_method :new
 
+    NOOP_UNSUBSCRIBE = -> {}.freeze
+    private_constant :NOOP_UNSUBSCRIBE
+
     def self.get(sdk_key = nil, config: nil)
       sdk_key ||= ENV["FEATUREFLIP_SDK_KEY"]
       raise ConfigurationError, "SDK key is required. Pass sdk_key parameter or set FEATUREFLIP_SDK_KEY env var." unless sdk_key
@@ -68,10 +71,15 @@ module Featureflip
     end
 
     def close
-      @close_mutex.synchronize do
+      subscriptions = @close_mutex.synchronize do
         return if @closed
+
         @closed = true
+        @subscriptions.dup.tap { @subscriptions.clear }
       end
+      # This handle's listeners only: the core is shared and other handles may
+      # still be subscribed.
+      subscriptions.each { |s| @core._remove_update_listener(s) }
       @core._release
     end
 
@@ -80,12 +88,53 @@ module Featureflip
       @core.restart
     end
 
+    # Subscribe to flag-configuration changes. The listener (a block or any
+    # #call-able) receives the sorted keys whose configuration changed, batched
+    # into one call per update. It runs on the SDK's streaming or polling
+    # thread, so it must not block.
+    #
+    # The initial flag load does NOT fire. Reported keys include flags added,
+    # removed or modified, flags referencing an edited segment, and flags
+    # depending on a changed flag through a prerequisite. A raising listener is
+    # logged and isolated.
+    #
+    # Returns a callable that unsubscribes (calling it twice is harmless). One
+    # dispatch already in flight may still reach the listener after the
+    # unsubscribe returns. While the fallback poller and the stream overlap
+    # (#3071) a listener can be called from two threads at once, so it must be
+    # thread-safe.
+    # Closing this handle drops every subscription it made.
+    def on_update(listener = nil, &block)
+      raise ArgumentError, "pass a listener or a block, not both" if listener && block
+
+      callable = listener || block
+      raise ArgumentError, "on_update requires a listener or a block" if callable.nil?
+      raise ArgumentError, "listener must respond to #call" unless callable.respond_to?(:call)
+
+      # A distinct wrapper per subscription, so registering the same callable
+      # twice yields two independently removable subscriptions.
+      subscription = ->(keys) { callable.call(keys) }
+      @close_mutex.synchronize do
+        return NOOP_UNSUBSCRIBE if @closed
+
+        @subscriptions << subscription
+        @core._add_update_listener(subscription)
+      end
+
+      lambda do
+        @close_mutex.synchronize { @subscriptions.delete_if { |s| s.equal?(subscription) } }
+        @core._remove_update_listener(subscription)
+        nil
+      end
+    end
+
     private
 
     def initialize(core)
       @core = core
       @closed = false
       @close_mutex = Mutex.new
+      @subscriptions = []
     end
   end
 end

data/lib/featureflip/data_source/polling.rb

@@ -17,9 +17,14 @@ module Featureflip
 
       def stop
         @stop_flag = true
-        @thread&.wakeup rescue nil
-        @thread&.join(5)
+        thread = @thread
         @thread = nil
+        # Called from a listener running on the poll thread: it can't join itself,
+        # and the stop flag ends its loop once the listener returns.
+        return if thread.nil? || thread.equal?(Thread.current)
+
+        thread.wakeup rescue nil
+        thread.join(5)
       end
 
       private

data/lib/featureflip/data_source/streaming.rb

@@ -36,7 +36,7 @@ module Featureflip
       RECONNECT_BASE_DELAY_SECONDS = 1
       MAX_BACKOFF_SECONDS = 30
 
-      def initialize(sdk_key:, config:, http_client:, on_flag_updated:, on_flag_deleted:, on_segment_updated:, on_error:, on_sync: nil, on_give_up: nil)
+      def initialize(sdk_key:, config:, http_client:, on_flag_updated:, on_flag_deleted:, on_segment_updated:, on_error:, on_sync: nil, on_fallback_to_polling: nil, on_recovered: nil)
         @sdk_key = sdk_key
         @config = config
         @http_client = http_client
@@ -45,10 +45,14 @@ module Featureflip
         @on_segment_updated = on_segment_updated
         @on_error = on_error
         @on_sync = on_sync
-        @on_give_up = on_give_up
+        @on_fallback_to_polling = on_fallback_to_polling
+        @on_recovered = on_recovered
         @stop_flag = false
         @thread = nil
         @retry_count = 0
+        # True between arming the polling fallback and the next delivered frame.
+        # Only ever touched from the streaming thread.
+        @fallback_active = false
         @current_event_type = nil
         @current_data = nil
         @line_buffer = String.new # ASCII-8BIT: raw read_body bytes concatenate safely
@@ -60,6 +64,7 @@ module Featureflip
       def start
         @stop_flag = false
         @retry_count = 0
+        @fallback_active = false
         @thread = Thread.new { run }
       end
 
@@ -72,6 +77,13 @@ module Featureflip
         @thread = nil
         return unless thread
 
+        # Called from a listener running ON the stream thread (close/restart from
+        # inside an on_update callback): raising into ourselves would fire
+        # StreamStopped synchronously mid-shutdown and joining ourselves would
+        # deadlock. The flag is set, so the read loop abandons the connection as soon
+        # as the listener returns.
+        return if thread.equal?(Thread.current)
+
         # Interrupt a thread blocked in read_body. Guard the raise: the thread may
         # finish between the alive? check and the raise (ThreadError on a dead one).
         begin
@@ -112,9 +124,14 @@ module Featureflip
             # purposes — otherwise an accept-then-close server never accumulates
             # toward max_stream_retries and never degrades to polling.
             @retry_count += 1
-            if @retry_count > @config.max_stream_retries
-              @on_give_up&.call
-              break
+            # The fallback is ADDITIVE, never terminal (#3071). Polling covers the
+            # outage; this loop keeps retrying the stream underneath at the capped
+            # backoff, and the next delivered frame retires the poller. Breaking out
+            # here left the process polling — and blind to real-time updates — until
+            # it restarted, after only ~31s of unreachability.
+            if @retry_count > @config.max_stream_retries && !@fallback_active
+              @fallback_active = true
+              @on_fallback_to_polling&.call
             end
           end
 
@@ -153,7 +170,12 @@ module Featureflip
           reset_stream_parser
           response.read_body do |chunk|
             break if @stop_flag
+
             feed_chunk(chunk)
+            # A listener on this thread may have stopped the handler while
+            # feed_chunk dispatched. Leave read_body now, which abandons the SSE
+            # connection, instead of blocking on the socket for the next chunk.
+            break if @stop_flag
           end
         end
 
@@ -173,6 +195,8 @@ module Featureflip
       def feed_chunk(chunk)
         @line_buffer << chunk
         while (newline_index = @line_buffer.index("\n"))
+          break if @stop_flag
+
           line = @line_buffer.slice!(0, newline_index + 1)
           process_sse_line(line.chomp.force_encoding(Encoding::UTF_8))
         end
@@ -189,6 +213,14 @@ module Featureflip
           @current_data = @current_data.nil? ? fragment : "#{@current_data}\n#{fragment}"
         elsif line.empty? && @current_event_type && @current_data
           @delivered_frame = true
+          # Retire the fallback poller HERE rather than when run() next comes round:
+          # connect() blocks in read_body for the whole lifetime of a healthy stream,
+          # so a reap on return would leave the poller alive that entire time, and its
+          # periodic whole-store replaces would revert deltas applied by this stream.
+          if @fallback_active
+            @fallback_active = false
+            @on_recovered&.call
+          end
           handle_event(@current_event_type, @current_data)
           @current_event_type = nil
           @current_data = nil

data/lib/featureflip/shared_core.rb

@@ -97,6 +97,8 @@ module Featureflip
       @ref_count = 1
       @ref_mutex = Mutex.new
       @shut_down = false
+      @update_listeners = []
+      @update_listeners_mutex = Mutex.new
 
       bootstrap!
     end
@@ -126,6 +128,17 @@ module Featureflip
       @config
     end
 
+    # Internal: Client#on_update's registry. Listeners are core-wide (one data
+    # source feeds every handle); Client tracks which ones each handle added so
+    # closing one handle never silences another's.
+    def _add_update_listener(listener)
+      @update_listeners_mutex.synchronize { @update_listeners << listener }
+    end
+
+    def _remove_update_listener(listener)
+      @update_listeners_mutex.synchronize { @update_listeners.delete_if { |l| l.equal?(listener) } }
+    end
+
     def _ref_count
       @ref_mutex.synchronize { @ref_count }
     end
@@ -276,6 +289,11 @@ module Featureflip
       @streaming_handler&.stop
       @polling_handler&.stop
       @event_processor&.stop
+      # Clear both before restarting: start_polling refuses to start a second
+      # poller while one is referenced, so a stopped-but-referenced handler here
+      # would leave a restarted non-streaming core with no data source at all.
+      @streaming_handler = nil
+      @polling_handler = nil
 
       if @config.streaming
         start_streaming
@@ -356,27 +374,44 @@ module Featureflip
         sdk_key: @sdk_key,
         config: @config,
         http_client: @http_client,
-        on_flag_updated: ->(flag) { @store.upsert(flag) },
-        on_flag_deleted: ->(key) { @store.remove_flag(key) },
-        on_segment_updated: ->(flags, segments) { @store.init(flags, segments) },
-        on_sync: ->(flags, segments) { @store.init(flags, segments) },
+        on_flag_updated: ->(flag) { apply_flag_update(flag) },
+        on_flag_deleted: ->(key) { apply_flag_delete(key) },
+        on_segment_updated: ->(flags, segments) { apply_snapshot(flags, segments) },
+        on_sync: ->(flags, segments) { apply_snapshot(flags, segments) },
         on_error: ->(_err) { },
-        on_give_up: -> { fallback_to_polling }
+        on_fallback_to_polling: -> { fallback_to_polling },
+        on_recovered: -> { stop_fallback_polling }
       )
       @streaming_handler.start
     end
 
     def fallback_to_polling
-      @config.logger&.warn("Featureflip: streaming retries exhausted, falling back to polling")
-      @streaming_handler = nil
+      @config.logger&.warn(
+        "Featureflip: streaming retries exhausted, falling back to polling while the stream keeps retrying"
+      )
+      # The handler is NOT cleared: it is still running and still trying to reopen
+      # the stream (#3071). Clearing it here is what used to make the fallback
+      # permanent — nothing would have restarted streaming.
       start_polling
     end
 
+    def stop_fallback_polling
+      return if @polling_handler.nil?
+
+      @config.logger&.info("Featureflip: stream recovered, stopping polling fallback")
+      @polling_handler.stop
+      @polling_handler = nil
+    end
+
     def start_polling
+      # Reachable from both start_data_source and the streaming fallback; a second
+      # call must not leak a second polling thread.
+      return if @polling_handler
+
       @polling_handler = DataSource::PollingHandler.new(
         http_client: @http_client,
         config: @config,
-        on_update: ->(flags, segments) { @store.init(flags, segments) },
+        on_update: ->(flags, segments) { apply_snapshot(flags, segments) },
         on_error: ->(_err) { }
       )
       @polling_handler.start
@@ -419,6 +454,41 @@ module Featureflip
       @store.get_segment(key)
     end
 
+    # Every data-source write funnels through one of these three so the change
+    # set is computed by the store and reported in one place.
+    def apply_snapshot(flags, segments)
+      notify_update_listeners(@store.init(flags, segments))
+    end
+
+    def apply_flag_update(flag)
+      notify_update_listeners(@store.upsert(flag))
+    end
+
+    def apply_flag_delete(key)
+      notify_update_listeners(@store.remove_flag(key))
+    end
+
+    # Runs on the streaming/polling thread, OUTSIDE the store lock: listeners are
+    # user code and may re-enter the client. Isolation mirrors
+    # notify_inspectors: everything is contained except the process-level errors
+    # in INSPECTOR_UNISOLATED_ERRORS, which no callback has the right to swallow.
+    def notify_update_listeners(keys)
+      return if keys.nil? || keys.empty?
+
+      listeners = @update_listeners_mutex.synchronize { @update_listeners.dup }
+      listeners.each do |listener|
+        begin
+          listener.call(keys.dup)
+        rescue *INSPECTOR_UNISOLATED_ERRORS, DataSource::StreamingHandler::StreamStopped
+          # StreamStopped is the stream's own shutdown signal (Thread#raise from
+          # StreamingHandler#stop), never a listener failure.
+          raise
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          @config.logger&.warn("Featureflip: flag update listener raised #{e.class}: #{e.message}")
+        end
+      end
+    end
+
     def normalize_context(context)
       return {} if context.nil?
       context.transform_keys(&:to_s)
@@ -521,6 +591,8 @@ module Featureflip
       @ref_count = 1
       @ref_mutex = Mutex.new
       @shut_down = false
+      @update_listeners = []
+      @update_listeners_mutex = Mutex.new
     end
 
     def self._configs_equal(a, b)

data/lib/featureflip/store/flag_store.rb

@@ -5,14 +5,22 @@ module Featureflip
         @flags = {}
         @segments = {}
         @mutex = Mutex.new
+        # The first snapshot establishes the baseline and reports nothing: a cold
+        # start is not a change (the cross-SDK on_update contract).
+        @has_snapshot = false
       end
 
+      # Replace the store with a full snapshot (initial fetch, poll tick, SSE
+      # `sync`, SSE segment refetch). Returns the changed flag keys, computed
+      # under the same lock as the replace so a concurrent writer can never make
+      # the reported change and the stored state disagree.
       def init(flags, segments)
         @mutex.synchronize do
-          @flags.clear
-          @segments.clear
-          flags.each { |f| @flags[f.key] = f }
-          segments.each { |s| @segments[s.key] = s }
+          changed = @has_snapshot ? UpdateDiff.diff_snapshot(@flags, @segments, flags, segments) : []
+          @flags = flags.to_h { |f| [f.key, f] }
+          @segments = segments.to_h { |s| [s.key, s] }
+          @has_snapshot = true
+          changed
         end
       end
 
@@ -42,16 +50,37 @@ module Featureflip
       # pre-edit config until an SSE `sync` or reconnect.
       #
       # Re-applying an identical config is harmless; dropping a real one is not.
+      #
+      # Returns the changed keys: none when the delta is rejected or is an
+      # identical redelivery (reconnects and duplicate events re-send the same
+      # config, and reporting those would make on_update noisy).
       def upsert(flag)
         @mutex.synchronize do
           existing = @flags[flag.key]
-          return if existing && existing.version > flag.version
+          return [] if existing && existing.version > flag.version
+
           @flags[flag.key] = flag
+          return [] if existing == flag
+
+          with_prerequisite_dependents(flag.key)
         end
       end
 
+      # Returns the deleted key plus its dependents, or [] if it was absent.
       def remove_flag(key)
-        @mutex.synchronize { @flags.delete(key) }
+        @mutex.synchronize do
+          return [] if @flags.delete(key).nil?
+
+          with_prerequisite_dependents(key)
+        end
+      end
+
+      private
+
+      # Caller holds @mutex. Reads the post-mutation store, so a deleted flag's
+      # dependents, which still carry the dangling prerequisite row, are reached.
+      def with_prerequisite_dependents(key)
+        UpdateDiff.add_prerequisite_dependents(@flags.values, Set[key]).to_a.sort
       end
     end
   end

data/lib/featureflip/store/update_diff.rb

@@ -0,0 +1,105 @@
+require "set"
+
+module Featureflip
+  module Store
+    # Change detection for Client#on_update.
+    #
+    # The store receives a *full* snapshot on every poll tick and every SSE
+    # `sync`, so notifying on each one would report "everything changed" once
+    # per poll interval. These functions reduce a snapshot to the flag keys whose
+    # evaluated value could actually have moved.
+    #
+    # A port of the python SDK's `_updates.py` (itself mirroring js-sdk
+    # `core/store.ts`). The semantics are cross-SDK contract, not an
+    # implementation detail.
+    module UpdateDiff
+      module_function
+
+      # Keys whose evaluated value may differ between two snapshots: added,
+      # removed and modified flags, then the flags a changed segment or a
+      # changed prerequisite drags along with them.
+      #
+      # Every model is a Struct, so `!=` is an exact config comparison.
+      # FlagConfiguration's memoised @variations_by_key is an ivar, not a
+      # member, so it does not take part.
+      def diff_snapshot(previous_flags, previous_segments, next_flags, next_segments)
+        changed = Set.new
+
+        next_flag_keys = Set.new
+        next_flags.each do |flag|
+          next_flag_keys << flag.key
+          previous = previous_flags[flag.key]
+          changed << flag.key if previous.nil? || previous != flag
+        end
+        # Removed server-side: still a change for anyone holding the old value.
+        previous_flags.each_key { |key| changed << key unless next_flag_keys.include?(key) }
+
+        changed_segments = Set.new
+        next_segment_keys = Set.new
+        next_segments.each do |segment|
+          next_segment_keys << segment.key
+          previous = previous_segments[segment.key]
+          changed_segments << segment.key if previous.nil? || previous != segment
+        end
+        previous_segments.each_key { |key| changed_segments << key unless next_segment_keys.include?(key) }
+
+        unless changed_segments.empty?
+          # A segment edit alters evaluation without bumping any flag's version,
+          # so the flags referencing it are pulled in by hand. Only incoming
+          # flags are scanned: a flag that dropped its reference to a changed
+          # segment had its own rules edited and is already reported above.
+          next_flags.each do |flag|
+            references = (flag.rules || []).any? do |rule|
+              rule.segment_key && changed_segments.include?(rule.segment_key)
+            end
+            changed << flag.key if references
+          end
+        end
+
+        # Must run last: it walks out from the fully-resolved set, so a flag only
+        # the segment scan pulled in still reaches its dependents.
+        add_prerequisite_dependents(next_flags, changed)
+        changed.to_a.sort
+      end
+
+      # Expands +changed+ (a Set, mutated and returned) with every transitive
+      # prerequisite dependent.
+      #
+      # A flag's version covers its own prerequisite rows, not the flags they
+      # point at, so toggling a prerequisite bumps only the prerequisite. The
+      # dependent's value still flips (to its off variation, PrerequisiteFailed),
+      # so it has to be reported by hand. Over-reporting is harmless; this
+      # prevents under-reporting.
+      #
+      # Pass the POST-change flags: a deleted flag's dependents are still
+      # present and still carry the now-dangling row, so they stay reachable.
+      def add_prerequisite_dependents(flags, changed)
+        return changed if changed.empty?
+
+        dependents = {}
+        flags.each do |flag|
+          (flag.prerequisites || []).each do |prerequisite|
+            key = prerequisite.prerequisite_flag_key
+            next if key.nil? || key.empty?
+
+            (dependents[key] ||= []) << flag.key
+          end
+        end
+        return changed if dependents.empty?
+
+        # `changed` doubles as the visited set, so a prerequisite cycle
+        # (rejected by the server, reachable via a malformed payload) terminates.
+        queue = changed.to_a
+        until queue.empty?
+          (dependents[queue.pop] || []).each do |dependent|
+            next if changed.include?(dependent)
+
+            changed << dependent
+            queue << dependent
+          end
+        end
+        changed
+      end
+    end
+  end
+end

data/lib/featureflip/version.rb

@@ -1,3 +1,3 @@
 module Featureflip
-  VERSION = "2.8.0"
+  VERSION = "2.10.0"
 end

data/lib/featureflip.rb

@@ -8,6 +8,7 @@ require_relative "featureflip/models/evaluation_event"
 require_relative "featureflip/evaluation/bucketing"
 require_relative "featureflip/evaluation/condition_evaluator"
 require_relative "featureflip/evaluation/evaluator"
+require_relative "featureflip/store/update_diff"
 require_relative "featureflip/store/flag_store"
 require_relative "featureflip/http/client"
 require_relative "featureflip/events/event"
@@ -85,6 +86,11 @@ module Featureflip
       @default_client.restart
     end
 
+    def on_update(listener = nil, &block)
+      ensure_configured!
+      @default_client.on_update(listener, &block)
+    end
+
     private
 
     def ensure_configured!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureflip
 version: !ruby/object:Gem::Version
-  version: 2.8.0
+  version: 2.10.0
 platform: ruby
 authors:
 - Featureflip
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-08 00:00:00.000000000 Z
+date: 2026-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -90,6 +90,7 @@ files:
 - lib/featureflip/models/segment.rb
 - lib/featureflip/shared_core.rb
 - lib/featureflip/store/flag_store.rb
+- lib/featureflip/store/update_diff.rb
 - lib/featureflip/version.rb
 homepage: https://featureflip.io
 licenses: