featureflip 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fdefb980d91435aca01a6f6344804e172dedef867fd826c5ac9a017ca6416ca
-  data.tar.gz: d98b0cda83055b8b984b2ea370b9717f6800dd44202ddacf21944fa19b0dc194
+  metadata.gz: fbe86937e4d8a9310f509da9c05ee1bcce31ebc4f633504249dd81429c586bbc
+  data.tar.gz: d71d56d4641775aafa8f11ef426adf40ea162e8a9eeb0ecafacb75998003c34d
 SHA512:
-  metadata.gz: 360a193a8d0557ba71c45ce1c3f341d008f34f34996434328f7aa2c1da3eee9ef7cc531953ffbd21b8f83fa2674e750139c456854e59a322c0099fe04f76cc0f
-  data.tar.gz: f4f292e068e49a8688b94c530d5cce50a060f97c57742e5aaee3f4db02aa469b0623c8b3c95065c6293e0452b71a58f3dc57212b649bc78e66044dad025c24a6
+  metadata.gz: f8bd1ce419e5d8ebf74696c34000e1fcb89eb9f34cf5136acb4fc28dff86ae91da031b16464ef1d4f74fed4141dfb3bbe2c1e0ef1651bb65dba3d268f6ad3419
+  data.tar.gz: 6dde7ff7991f6e29f88c56253578200ee7b981ed754c86c5c1555fb4dfa847e02f0e23542c7c1ce509ec26c631083342d16ca67433aef99fc50316cedc92ce9c

data/lib/featureflip/config.rb

@@ -4,6 +4,11 @@ module Featureflip
                   :flush_batch_size, :init_timeout, :connect_timeout, :read_timeout,
                   :max_stream_retries, :send_events, :logger
 
+    # 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.
+    attr_reader :inspectors
+
     def initialize(
       sdk_key: nil,
       base_url: "https://eval.featureflip.io",
@@ -16,7 +21,8 @@ module Featureflip
       read_timeout: 10,
       max_stream_retries: 5,
       send_events: true,
-      logger: nil
+      logger: nil,
+      inspectors: nil
     )
       @sdk_key = sdk_key
       @base_url = base_url
@@ -30,10 +36,23 @@ module Featureflip
       @max_stream_retries = max_stream_retries
       @send_events = send_events
       @logger = logger || default_logger
+      self.inspectors = inspectors
 
       validate!
     end
 
+    # Accepts a single callable or an array of callables. Anything that does not
+    # respond to #call is filtered out here, so the evaluation path never has to
+    # guard against it.
+    def inspectors=(value)
+      list = case value
+             when nil then []
+             when Array then value
+             else [value]
+             end
+      @inspectors = list.select { |i| i.respond_to?(:call) }.freeze
+    end
+
     def validate!
       finalize!
       validate_positive_fields!

data/lib/featureflip/data_source/streaming.rb

@@ -5,7 +5,38 @@ require "json"
 module Featureflip
   module DataSource
     class StreamingHandler
-      def initialize(sdk_key:, config:, http_client:, on_flag_updated:, on_flag_deleted:, on_segment_updated:, on_error:, on_give_up: nil)
+      # Raised into the streaming thread by #stop to interrupt a blocking read
+      # (Thread#wakeup only wakes a *sleeping* thread; it can't interrupt an
+      # MRI IO read — Thread#raise can). Inherits from Exception, not
+      # StandardError, so it bypasses handle_event's/run's generic `rescue
+      # StandardError` arms (which would otherwise swallow a stop mid-event and
+      # leave the thread blocking) and is only caught by the explicit
+      # `rescue StreamStopped`.
+      class StreamStopped < Exception; end # rubocop:disable Lint/InheritException
+
+      # The server sends a keep-alive ping this often; a finite read timeout at
+      # or below this interval would sever a healthy stream.
+      SERVER_PING_INTERVAL_SECONDS = 30
+
+      # Client-side liveness watchdog. net/http gives us no separate heartbeat,
+      # so the read timeout IS the watchdog: if no data (not even a ping) arrives
+      # for this long the socket is treated as dead — a half-open connection
+      # (LB/NAT idle-drop or a partition with no FIN/RST) — and the blocking read
+      # raises Net::ReadTimeout, which drives reconnect/backoff/polling. Set to
+      # 3× the ping (3 missed pings) so it never severs a healthy stream but still
+      # detects a dead socket within a bounded time. MUST stay finite and
+      # > SERVER_PING_INTERVAL_SECONDS. (The rest of the server family now runs the
+      # same finite 90s watchdog — java readTimeout(90s) / python read=90.0 / csharp
+      # an idle-timeout CTS reset per event — so half-open detection is uniform.)
+      STREAM_READ_TIMEOUT = SERVER_PING_INTERVAL_SECONDS * 3
+
+      # Base reconnect backoff; also the floor applied after a healthy stream
+      # closes cleanly, so even an accept-then-immediately-close server is
+      # throttled instead of busy-looping.
+      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)
         @sdk_key = sdk_key
         @config = config
         @http_client = http_client
@@ -13,12 +44,17 @@ module Featureflip
         @on_flag_deleted = on_flag_deleted
         @on_segment_updated = on_segment_updated
         @on_error = on_error
+        @on_sync = on_sync
         @on_give_up = on_give_up
         @stop_flag = false
         @thread = nil
         @retry_count = 0
         @current_event_type = nil
         @current_data = nil
+        @line_buffer = String.new # ASCII-8BIT: raw read_body bytes concatenate safely
+        @delivered_frame = false
+        @wake_mutex = Mutex.new
+        @wake_cond = ConditionVariable.new
       end
 
       def start
@@ -29,9 +65,21 @@ module Featureflip
 
       def stop
         @stop_flag = true
-        @thread&.wakeup rescue nil
-        @thread&.join(5)
+        # Wake an in-progress backoff wait.
+        @wake_mutex.synchronize { @wake_cond.broadcast }
+
+        thread = @thread
         @thread = nil
+        return unless thread
+
+        # 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
+          thread.raise(StreamStopped.new) if thread.alive?
+        rescue ThreadError
+          # Thread already finished — nothing to interrupt.
+        end
+        thread.join(5)
       end
 
       private
@@ -40,26 +88,57 @@ module Featureflip
         until @stop_flag
           begin
             connect
+          rescue StreamStopped
+            break
           rescue StandardError => e
             break if @stop_flag
             @on_error.call(e)
+          end
+          break if @stop_flag
+
+          # Consult @delivered_frame (the instance var), NOT connect's return
+          # value: connect only *returns* on a clean EOF, but the common stream
+          # terminations (the liveness-watchdog Net::ReadTimeout, ECONNRESET,
+          # IOError) RAISE — and a session that delivered frames before raising
+          # must still count as healthy, or transient blips accumulate and
+          # wrongly degrade a good stream to polling. @delivered_frame survives
+          # the exception; connect resets it to false at the top of each attempt.
+          if @delivered_frame
+            # The stream genuinely stayed up (delivered ≥1 frame — the server
+            # sends `sync` first). Reset the failure counter.
+            @retry_count = 0
+          else
+            # A clean EOF (no frame) is treated as a failure for backoff/escalation
+            # 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
             end
-            delay = [2**(@retry_count - 1), 30].min
-            sleep(delay)
           end
+
+          # Back off before every reconnect, including after a clean EOF, so we
+          # never zero-delay busy-loop against a flapping endpoint.
+          backoff_wait(backoff_delay(@retry_count))
         end
+      rescue StreamStopped
+        # stop() interrupted a backoff wait — clean shutdown.
       end
 
+      # Connect to the SSE stream and process events until the connection ends.
+      # Returns true if the stream delivered at least one complete frame (a live
+      # stream), false if it returned 200 but closed without delivering one.
       def connect
+        # Reset before anything can raise (a failed handshake / connection error
+        # must not let run() read a stale `true` from the previous session).
+        @delivered_frame = false
+
         uri = URI("#{@config.base_url}/v1/sdk/stream")
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = uri.scheme == "https"
         http.open_timeout = @config.connect_timeout
-        http.read_timeout = 300 # 5 min — detect silent TCP drops
+        http.read_timeout = STREAM_READ_TIMEOUT
 
         req = Net::HTTP::Get.new(uri.request_uri)
         req["Authorization"] = @sdk_key
@@ -71,31 +150,67 @@ module Featureflip
             raise Featureflip::Error, "SSE connection failed: #{response.code}"
           end
 
-          @retry_count = 0
-          @current_event_type = nil
-          @current_data = nil
-
+          reset_stream_parser
           response.read_body do |chunk|
             break if @stop_flag
-            chunk.each_line do |line|
-              process_sse_line(line.strip)
-            end
+            feed_chunk(chunk)
           end
         end
+
+        @delivered_frame
+      end
+
+      def reset_stream_parser
+        @current_event_type = nil
+        @current_data = nil
+        @line_buffer = String.new # ASCII-8BIT: raw read_body bytes concatenate safely
+      end
+
+      # Append a raw SSE body chunk and dispatch every *complete* line it
+      # completes. Net::HTTP#read_body yields arbitrary byte fragments with no
+      # line alignment, so a line (or a `data:` payload) can span chunk
+      # boundaries; buffer until a newline before parsing.
+      def feed_chunk(chunk)
+        @line_buffer << chunk
+        while (newline_index = @line_buffer.index("\n"))
+          line = @line_buffer.slice!(0, newline_index + 1)
+          process_sse_line(line.chomp.force_encoding(Encoding::UTF_8))
+        end
       end
 
       def process_sse_line(line)
         if line.start_with?("event: ")
           @current_event_type = line[7..]
         elsif line.start_with?("data: ")
-          @current_data = line[6..]
+          # Per the SSE spec multiple data: lines join with "\n" — concatenate,
+          # never overwrite, or a chunked/multi-line payload loses everything but
+          # its last fragment.
+          fragment = line[6..]
+          @current_data = @current_data.nil? ? fragment : "#{@current_data}\n#{fragment}"
         elsif line.empty? && @current_event_type && @current_data
+          @delivered_frame = true
           handle_event(@current_event_type, @current_data)
           @current_event_type = nil
           @current_data = nil
         end
       end
 
+      # Capped exponential backoff. failures == 0 means a healthy stream just
+      # closed cleanly; still apply the base floor so we don't busy-loop.
+      def backoff_delay(failures)
+        exponent = failures <= 0 ? 0 : failures - 1
+        [RECONNECT_BASE_DELAY_SECONDS * (2**exponent), MAX_BACKOFF_SECONDS].min
+      end
+
+      # Sleep for `seconds`, but return immediately if stop() fires — so a pending
+      # shutdown isn't blocked behind a long backoff.
+      def backoff_wait(seconds)
+        @wake_mutex.synchronize do
+          return if @stop_flag
+          @wake_cond.wait(@wake_mutex, seconds)
+        end
+      end
+
       def handle_event(event_type, data)
         case event_type
         when "flag.created", "flag.updated"
@@ -112,6 +227,12 @@ module Featureflip
         when "segment.updated"
           flags, segments = @http_client.get_flags
           @on_segment_updated.call(flags, segments)
+        when "sync"
+          # Full config snapshot the server sends on (re)connect. Replace the
+          # whole store so flags changed OR deleted during a disconnect are
+          # re-synced. Full replace, never a per-key merge.
+          flags, segments = @http_client.parse_flags_response(JSON.parse(data))
+          @on_sync&.call(flags, segments)
         end
       rescue StandardError
         # Swallow event processing errors

data/lib/featureflip/http/client.rb

@@ -13,7 +13,13 @@ module Featureflip
 
       def get_flags
         response = request(:get, "/v1/sdk/flags")
-        data = JSON.parse(response.body)
+        parse_flags_response(JSON.parse(response.body))
+      end
+
+      # Parse a GET /v1/sdk/flags-shaped snapshot into models. Reused for the
+      # connect-time `sync` SSE snapshot, which carries the identical payload
+      # shape inline (no extra HTTP round-trip).
+      def parse_flags_response(data)
         flags = (data["flags"] || []).map { |f| parse_flag(f) }
         segments = (data["segments"] || []).map { |s| parse_segment(s) }
         [flags, segments]

data/lib/featureflip/models/evaluation_event.rb

@@ -0,0 +1,29 @@
+module Featureflip
+  module Models
+    # The payload handed to every registered evaluation inspector, once per
+    # variation call. This is the frozen cross-SDK inspector contract (see
+    # docs/superpowers/specs/2026-07-13-sdk-onevaluation-inspector-design.md),
+    # spelled in Ruby snake_case:
+    #
+    #   flag_key         the flag key evaluated
+    #   context          the full evaluation context -- a copy, so mutating it
+    #                    cannot affect the caller's hash
+    #   value            the value the caller actually receives (default applied)
+    #   variation_key    winning arm; nil on flag-not-found and on error
+    #   reason           this SDK's native reason string (PascalCase, matching
+    #                    EvaluationDetail#reason -- deliberately NOT converted)
+    #   rule_id          set only on a rule match
+    #   prerequisite_key set only on a prerequisite failure
+    #   timestamp        ISO-8601 string
+    EvaluationEvent = Struct.new(
+      :flag_key, :context, :value, :variation_key, :reason,
+      :rule_id, :prerequisite_key, :timestamp,
+      keyword_init: true
+    ) do
+      def initialize(flag_key:, context:, value:, reason:, timestamp:,
+                     variation_key: nil, rule_id: nil, prerequisite_key: nil)
+        super
+      end
+    end
+  end
+end

data/lib/featureflip/shared_core.rb

@@ -1,10 +1,36 @@
 require "timeout"
+require "time"
 
 module Featureflip
   class SharedCore
     LIVE_CORES = {}
     LIVE_CORES_MUTEX = Mutex.new
 
+    # Exception classes that are deliberately NOT isolated when an evaluation
+    # inspector raises them (see #notify_inspectors). Everything else -- every
+    # StandardError, plus the Exception-but-not-StandardError classes a buggy
+    # callback realistically raises (NotImplementedError and other ScriptErrors,
+    # Minitest::Assertion, RSpec::Expectations::ExpectationNotMetError) -- is
+    # caught and logged so the caller's value is never affected.
+    #
+    # These four are re-raised because swallowing them would break something the
+    # inspector has no business breaking:
+    #   SystemExit        `exit`/`abort` -- the process is deliberately going down
+    #   SignalException   SIGTERM and (via its subclass Interrupt) Ctrl-C
+    #   NoMemoryError     the VM is out of memory; there is nothing safe to do
+    #   SystemStackError  the stack is blown; unwinding is the only safe move
+    # Timeout::ExitException is the private class `Timeout.timeout` throws into
+    # the running thread to unwind it; eating it would silently neutralise a
+    # caller that wrapped its variation call in a timeout.
+    INSPECTOR_UNISOLATED_ERRORS = [
+      SystemExit,
+      SignalException,
+      NoMemoryError,
+      SystemStackError,
+      (Timeout::ExitException if defined?(Timeout::ExitException))
+    ].compact.freeze
+    private_constant :INSPECTOR_UNISOLATED_ERRORS
+
     # --- Class-level factory methods ---
 
     def self._get_or_create(sdk_key, config)
@@ -52,6 +78,12 @@ module Featureflip
     def initialize(sdk_key:, config:)
       @sdk_key = sdk_key
       @config = config
+      # Snapshot the (already-filtered) inspector list at construction: config is
+      # immutable-after-init from the core's point of view, so the evaluation path
+      # needs no locking. Deliberately excluded from _configs_equal -- callables
+      # aren't structurally comparable and a differing inspector must not trigger
+      # the "different config" warning.
+      @inspectors = config.inspectors || []
       @store = Store::FlagStore.new
       @evaluator = Evaluation::Evaluator.new
       @initialized = false
@@ -124,6 +156,8 @@ module Featureflip
       context = normalize_context(context)
 
       if @test_mode
+        # Test-mode cores are built by _create_for_testing, which has no user
+        # config, so there are never inspectors to notify here.
         value = @test_values.fetch(key, default_value)
         reason = @test_values.key?(key) ? "Fallthrough" : "FlagNotFound"
         return Models::EvaluationDetail.new(value: value, reason: reason)
@@ -132,6 +166,7 @@ module Featureflip
       flag = @store.get_flag(key)
       unless flag
         record_evaluation(key, context, nil)
+        notify_inspectors(key, context, default_value, reason: "FlagNotFound")
         return Models::EvaluationDetail.new(value: default_value, reason: "FlagNotFound")
       end
 
@@ -141,12 +176,33 @@ module Featureflip
         get_segment: method(:get_segment),
         all_flags: @store.all_flags_map
       )
+
+      # Malformed config: the evaluator selected a variation key the flag does
+      # not define (e.g. a fallthrough/rule naming a since-deleted variation).
+      # Degrade to the caller's default and report Error, mirroring the engine's
+      # ServeVariation + the C#/Java SDKs (#1989). A variation that genuinely
+      # exists with a nil value is NOT this case -- hence the key lookup rather
+      # than a `value.nil?` check, which cannot tell the two apart.
+      reason = if result.variation_key && !result.variation_key.empty? &&
+                  flag.get_variation(result.variation_key).nil?
+                 "Error"
+               else
+                 result.reason
+               end
+
       value = result.value.nil? ? default_value : result.value
       record_evaluation(key, context, result.variation_key)
+      notify_inspectors(
+        key, context, value,
+        reason: reason,
+        variation_key: result.variation_key,
+        rule_id: result.rule_id,
+        prerequisite_key: result.prerequisite_key
+      )
 
       Models::EvaluationDetail.new(
         value: value,
-        reason: result.reason,
+        reason: reason,
         rule_id: result.rule_id,
         variation_key: result.variation_key,
         prerequisite_key: result.prerequisite_key
@@ -155,6 +211,7 @@ module Featureflip
       # Prerequisite-resolution failures return PrerequisiteFailed cleanly through
       # the evaluator; this rescue only fires on unexpected exceptions (malformed
       # config, programming errors), so prerequisite_key has no defined value.
+      notify_inspectors(key, context, default_value, reason: "Error")
       Models::EvaluationDetail.new(value: default_value, reason: "Error", prerequisite_key: nil)
     end
 
@@ -278,6 +335,7 @@ module Featureflip
         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_error: ->(_err) { },
         on_give_up: -> { fallback_to_polling }
       )
@@ -341,9 +399,51 @@ module Featureflip
       })
     end
 
+    # Fire the registered evaluation inspectors. Called once per variation call
+    # on every exit path of variation_detail (success, flag-not-found, error)
+    # with the reason and value the caller actually receives. A raising inspector
+    # is isolated: it neither changes the returned value nor stops its siblings.
+    def notify_inspectors(flag_key, context, value, reason:, variation_key: nil,
+                          rule_id: nil, prerequisite_key: nil)
+      return if @inspectors.nil? || @inspectors.empty?
+
+      event = Models::EvaluationEvent.new(
+        flag_key: flag_key,
+        # Shallow copy so a buggy inspector cannot mutate the caller's hash.
+        context: context.dup,
+        value: value,
+        variation_key: variation_key,
+        reason: reason,
+        rule_id: rule_id,
+        prerequisite_key: prerequisite_key,
+        # Millisecond precision, matching the sibling SDKs (PHP's "Y-m-d\TH:i:s.v\Z",
+        # C#'s "o", Python's isoformat). Whole-second stamps make an analytics sink
+        # that de-duplicates on (flag, user, timestamp) drop repeat exposures inside
+        # the same second, so the digit argument is load-bearing -- don't drop it.
+        timestamp: Time.now.utc.iso8601(3)
+      )
+
+      @inspectors.each do |inspector|
+        begin
+          inspector.call(event)
+        # Order matters: the un-isolated list is matched first, then everything
+        # else is contained. `rescue StandardError` is too narrow (an assertion
+        # failure or NotImplementedError from an inspector would escape into the
+        # caller's request handler, which the inspector contract forbids) and a
+        # bare `rescue Exception` is too wide (it would eat Ctrl-C). See
+        # INSPECTOR_UNISOLATED_ERRORS above before changing either arm.
+        rescue *INSPECTOR_UNISOLATED_ERRORS
+          raise
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          @config.logger&.warn("Featureflip: evaluation inspector raised #{e.class}: #{e.message}")
+        end
+      end
+    end
+
     def init_test_mode(flags)
       @sdk_key = "test-key"
       @config = Config.new
+      @inspectors = []
       @store = Store::FlagStore.new
       @evaluator = Evaluation::Evaluator.new
       @initialized = true

data/lib/featureflip/version.rb

@@ -1,3 +1,3 @@
 module Featureflip
-  VERSION = "2.2.0"
+  VERSION = "2.4.0"
 end

data/lib/featureflip.rb

@@ -4,6 +4,7 @@ require_relative "featureflip/config"
 require_relative "featureflip/models/flag"
 require_relative "featureflip/models/segment"
 require_relative "featureflip/models/evaluation_detail"
+require_relative "featureflip/models/evaluation_event"
 require_relative "featureflip/evaluation/bucketing"
 require_relative "featureflip/evaluation/condition_evaluator"
 require_relative "featureflip/evaluation/evaluator"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureflip
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Featureflip
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-19 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
 description: Server-side SDK for evaluating feature flags with Featureflip
 email:
 executables: []
@@ -85,6 +85,7 @@ files:
 - lib/featureflip/events/event_processor.rb
 - lib/featureflip/http/client.rb
 - lib/featureflip/models/evaluation_detail.rb
+- lib/featureflip/models/evaluation_event.rb
 - lib/featureflip/models/flag.rb
 - lib/featureflip/models/segment.rb
 - lib/featureflip/shared_core.rb