featureflip 2.9.0 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dfdc2e9de3795a36a917d2a748184853bbd1c30362dd313ac70e386a4d0758c
-  data.tar.gz: e878ef6a553b2948435fc004b905f84015433b42625721d41311c5cb55e87654
+  metadata.gz: 7dbbc4e1eefae9adf8a818fc31905e674ee68369be22f6d558f1838604a34fba
+  data.tar.gz: 91ddda08b1eb8015d297c4a6206d8df48704cde620908634bdc7c5415b6e3cb4
 SHA512:
-  metadata.gz: 871ae6a42bfcc7663a805a70935e2ac6b5a746a879df937343239f5f833c00be0990890f0ec47684a1beca0507160439274e26a606ef957510a3aa400d442929
-  data.tar.gz: d793281fb6b00d5cfeb5226c89c035fa17d6fad5d7af1876eac1c7d8c4c1290452c2067b6b9c8106795e4511451e43ef4debc399e660b245b3f7685507c494af
+  metadata.gz: 1c77f14b1245ebd4453d878c41fbadbea5051cee8b86eb5a9aed6fb210714b71275792b19cf571e62ccacce985babf303db5eeb81875fd6a18009bb169ef5506
+  data.tar.gz: 0ea6aba2d012d330c976e2fee16be73aee7d3ec1392a7bc0677147b2e1d7bac1a33b7048b59afaad82fd72339e984421ddb358339bedb220bacb66b8fa572e55

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/config.rb

@@ -4,6 +4,15 @@ module Featureflip
                   :flush_batch_size, :init_timeout, :connect_timeout, :read_timeout,
                   :max_stream_retries, :send_events, :logger
 
+    # Identifies a library that wraps this SDK, such as the OpenFeature provider. Its
+    # token is sent after the SDK's own in the User-Agent
+    # (`featureflip-ruby/<version> my-wrapper/1.0.0`) so usage through the wrapper can be
+    # counted. Both parts must be valid HTTP tokens; an invalid wrapper is ignored with a
+    # logged warning. wrapper_version may be nil. Leave unset when calling the SDK
+    # directly. Excluded from SharedCore._configs_equal: it identifies the caller rather
+    # than changing behavior.
+    attr_accessor :wrapper_name, :wrapper_version
+
     # Evaluation inspectors -- callables invoked once per variation call with a
     # Models::EvaluationEvent. Always an Array; non-callable entries are dropped
     # on assignment rather than blowing up on the evaluation hot path.
@@ -22,7 +31,9 @@ module Featureflip
       max_stream_retries: 5,
       send_events: true,
       logger: nil,
-      inspectors: nil
+      inspectors: nil,
+      wrapper_name: nil,
+      wrapper_version: nil
     )
       @sdk_key = sdk_key
       @base_url = base_url
@@ -37,6 +48,8 @@ module Featureflip
       @send_events = send_events
       @logger = logger || default_logger
       self.inspectors = inspectors
+      @wrapper_name = wrapper_name
+      @wrapper_version = wrapper_version
 
       validate!
     end
@@ -53,6 +66,13 @@ module Featureflip
       @inspectors = list.select { |i| i.respond_to?(:call) }.freeze
     end
 
+    # The User-Agent for every request: the SDK token, then the wrapper's (#4154). Built
+    # on first use and memoized, so the HTTP client and the stream share one value and an
+    # invalid wrapper is warned about once.
+    def user_agent
+      @user_agent ||= SdkIdentity.user_agent(self)
+    end
+
     def validate!
       finalize!
       validate_positive_fields!

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

@@ -77,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
@@ -153,7 +160,9 @@ module Featureflip
         req = Net::HTTP::Get.new(uri.request_uri)
         req["Authorization"] = @sdk_key
         req["Accept"] = "text/event-stream"
-        req["User-Agent"] = "featureflip-ruby/#{Featureflip::VERSION}"
+        # Same memoized value as the HTTP client, so an invalid wrapper is warned about
+        # once rather than on every reconnect.
+        req["User-Agent"] = @config.user_agent
 
         http.request(req) do |response|
           unless response.is_a?(Net::HTTPSuccess)
@@ -163,7 +172,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
 
@@ -183,6 +197,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

data/lib/featureflip/http/client.rb

@@ -83,7 +83,7 @@ module Featureflip
 
         req["Authorization"] = @sdk_key
         req["Content-Type"] = "application/json"
-        req["User-Agent"] = "featureflip-ruby/#{Featureflip::VERSION}"
+        req["User-Agent"] = @config.user_agent
 
         response = http.request(req)
 

data/lib/featureflip/sdk_identity.rb

@@ -0,0 +1,27 @@
+module Featureflip
+  # The User-Agent every request carries so the Evaluation API can count SDK usage by
+  # name and version (#4154, contract in #4138): `featureflip-ruby/<version>`, then the
+  # configured wrapper's token. VERSION is the constant the publish workflow rewrites,
+  # never a second literal (#2141).
+  module SdkIdentity
+    # RFC 9110 product token: tchars.
+    TOKEN = /\A[!#$%&'*+.^_`|~0-9A-Za-z-]+\z/
+
+    def self.user_agent(config)
+      sdk = "featureflip-ruby/#{Featureflip::VERSION}"
+      name = config.wrapper_name
+      return sdk if name.nil? || name.to_s.empty?
+
+      version = config.wrapper_version
+      unless TOKEN.match?(name.to_s) && (version.nil? || TOKEN.match?(version.to_s))
+        # Dropped rather than raised: identity metadata must never stop the client starting.
+        config.logger.warn(
+          "Featureflip: ignoring wrapper '#{name}/#{version}': not a valid User-Agent product token"
+        )
+        return sdk
+      end
+
+      version.nil? ? "#{sdk} #{name}" : "#{sdk} #{name}/#{version}"
+    end
+  end
+end

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
@@ -361,10 +374,10 @@ 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_fallback_to_polling: -> { fallback_to_polling },
         on_recovered: -> { stop_fallback_polling }
@@ -398,7 +411,7 @@ module Featureflip
       @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
@@ -441,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)
@@ -543,8 +591,12 @@ module Featureflip
       @ref_count = 1
       @ref_mutex = Mutex.new
       @shut_down = false
+      @update_listeners = []
+      @update_listeners_mutex = Mutex.new
     end
 
+    # wrapper_name/wrapper_version are deliberately excluded: they identify the caller
+    # rather than change behavior (see Config).
     def self._configs_equal(a, b)
       a.base_url == b.base_url &&
         a.streaming == b.streaming &&

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.9.0"
+  VERSION = "2.11.0"
 end

data/lib/featureflip.rb

@@ -1,6 +1,7 @@
 require_relative "featureflip/version"
 require_relative "featureflip/errors"
 require_relative "featureflip/config"
+require_relative "featureflip/sdk_identity"
 require_relative "featureflip/models/flag"
 require_relative "featureflip/models/segment"
 require_relative "featureflip/models/evaluation_detail"
@@ -8,6 +9,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 +87,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.9.0
+  version: 2.11.0
 platform: ruby
 authors:
 - Featureflip
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -88,8 +88,10 @@ files:
 - lib/featureflip/models/evaluation_event.rb
 - lib/featureflip/models/flag.rb
 - lib/featureflip/models/segment.rb
+- lib/featureflip/sdk_identity.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: