featureflip 2.5.0 → 2.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3e88364434f9dced8db82624524bf1ffe905b35b5ae8a062896bfb6c02dc5e6
-  data.tar.gz: 87d5bdaa62bb9f6e8eb0685f235315b31adfb5cd0dbdaac478965144a09709ff
+  metadata.gz: edea6a4841539f13194e1e03e76bd7db298e713a0d79ec66327838cc56ed8408
+  data.tar.gz: 5a2d3f0946e19fb1734bc7db35dc1006f5d39f22626cbd147f527c31aa8dbddd
 SHA512:
-  metadata.gz: 7b9c0cbfce3e7451f4218dc5a0274a28181d770a5689427d5fba20899702c5a580413b6adcb99482c717708cc2b60cccd5e9ee6dfb423351ff82024befae0477
-  data.tar.gz: d4c066e87770edfa6881cf000d36cc8e7f9f476cc3afebc8b44e5842f2c5946805af79a47dbceb575bd4e50496e56d024b3485fa083d414fb52bf8809b25eff2
+  metadata.gz: 894e77cfd032b59b62a8b1f9832ad5370d042c20290604b7f836bf9f35c427503f1b29eb3495c80fa02f816ae60e9d6c45c2d9f2074a9621aeb2cdaf1dd9d235
+  data.tar.gz: 472b4f2dbeb2dc1806a7e2dba1128b26bbe52a63833fcdd0c4571abc7b300b7d61ee153fe80cd35462c3782bbedee3b76695093c617a14600972e296f8c3ea53

data/lib/featureflip/data_source/streaming.rb

@@ -234,6 +234,15 @@ module Featureflip
           flags, segments = @http_client.parse_flags_response(JSON.parse(data))
           @on_sync&.call(flags, segments)
         end
+      rescue UnevaluableEntityError => e
+        # Not a malformed payload: the frame was well-formed and simply described
+        # behaviour this build cannot evaluate, so the entity was dropped rather than
+        # the payload discarded (#2402). Logged at the same volume — a flag that
+        # silently stopped updating is exactly as confusing as one that never arrived.
+        @config.logger&.warn(
+          "Featureflip: dropping #{event_type} update: #{e.message}. This SDK version " \
+          "may be older than the flag configuration."
+        )
       rescue MalformedPayloadError => e
         # A payload that violates the wire contract is discarded WHOLESALE rather
         # than partially applied — a half-parsed snapshot silently mis-evaluates

data/lib/featureflip/errors.rb

@@ -11,4 +11,40 @@ module Featureflip
   # operator to no-match. Only a TYPE violation is rejected, because that can never
   # be a legitimate newer-server payload. See #2285.
   class MalformedPayloadError < Error; end
+
+  # Raised when the API answers a request with a non-success status. Carries the status
+  # so a caller can decide what to do about it.
+  #
+  # The events flush is the caller that has to: it re-queues a batch a later attempt could
+  # plausibly deliver (5xx, 429) and drops one the server will reject identically forever
+  # (401/403 = key rejected, 400 = malformed body). Before this the status only existed
+  # inside the message string, so every failure looked alike and the batch was dropped
+  # either way (#2456).
+  #
+  # Subclasses Error and keeps the historical "HTTP <code>: <path>" message, so callers
+  # rescuing Featureflip::Error — or matching on that message — are unaffected.
+  class HttpStatusError < Error
+    attr_reader :status
+
+    def initialize(status, path)
+      @status = status
+      super("HTTP #{status}: #{path}")
+    end
+  end
+
+  # Raised when a flag or segment carries an enum value this SDK build cannot
+  # EVALUATE — an unrecognised `serve.type` or `conditionLogic` (#2402).
+  #
+  # Distinct from MalformedPayloadError, and the distinction is the whole point. That
+  # one means the payload is the wrong SHAPE and is discarded wholesale. This one means
+  # the payload is perfectly well-formed and simply describes behaviour a newer server
+  # understands and this build does not — so only the containing ENTITY is dropped and
+  # the rest of the configuration still applies.
+  #
+  # Not raised for an unrecognised condition OPERATOR: the evaluator already fails an
+  # unknown operator closed (#2262), so the condition just does not match and the flag
+  # remains perfectly evaluable. `serve.type` and `conditionLogic` have no such
+  # fail-closed arm — each dispatches on a two-way branch and an unrecognised value
+  # takes the ELSE arm, silently serving a rollout or matching ANY condition.
+  class UnevaluableEntityError < Error; end
 end

data/lib/featureflip/evaluation/condition_evaluator.rb

@@ -32,6 +32,14 @@ module Featureflip
         targets = condition.values.map(&:to_s)
 
         result = evaluate_operator(condition.operator, str_value, targets)
+
+        # Issue #2262: an unrecognised operator fails CLOSED. `!nil` is `true`
+        # in Ruby, so without this guard a negated unknown operator would match
+        # every user and roll the flag out to 100% of traffic. The realistic
+        # trigger is a new operator shipped server-side reaching an SDK pinned
+        # to an older version.
+        return false if result.nil?
+
         condition.negate ? !result : result
       end
 
@@ -66,16 +74,32 @@ module Featureflip
       SemverVersion = Struct.new(:release, :prerelease)
       private_constant :SemverVersion
 
-      # An ISO-8601 date-time with no timezone offset (no trailing "Z"/±hh:mm),
-      # so it must be assumed UTC before parsing.
-      ISO_NO_OFFSET = /\A\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?\z/
-      private_constant :ISO_NO_OFFSET
-
-      # A bare ISO-8601 calendar date ("2024-01-01") with no time component. The
-      # engine's DateTimeOffset.TryParse accepts these (midnight, assumed UTC),
-      # but Time.iso8601 rejects them, so they need their own midnight-UTC path.
-      ISO_DATE_ONLY = /\A\d{4}-\d{2}-\d{2}\z/
-      private_constant :ISO_DATE_ONLY
+      # The ONLY characters trimmed from a date operand, and the whole of the
+      # operand's permitted whitespace: U+0009..U+000D plus U+0020 -- exactly the
+      # class the engine's NumberStyles.Integer accepts via AllowLeadingWhite |
+      # AllowTrailingWhite.
+      #
+      # String#strip is deliberately NOT used: it also strips NUL, so "\0005" was
+      # trimmed to "5" and matched here while the engine rejected it (#2468).
+      OPERAND_WHITESPACE = "\t\n\v\f\r "
+      private_constant :OPERAND_WHITESPACE
+
+      # Characters no date operand may contain: a NUL or other control character, or
+      # a non-ASCII whitespace/format character. An interior ASCII space is allowed
+      # -- it is the ISO-8601 date/time separator.
+      FORBIDDEN_OPERAND_CHAR =
+        /[\u0000-\u001f\u007f-\u009f\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]/
+      private_constant :FORBIDDEN_OPERAND_CHAR
+
+      # The ISO-8601 grammar a date operand may use: a calendar date, optionally
+      # followed by a time (seconds and fractional seconds optional) and an optional
+      # offset in either extended (+05:00 / Z) or basic (+0500) form. The separator
+      # may be "T" or a space -- the engine accepts both, but Time.iso8601 rejects
+      # the space, which is why ruby alone read "2024-01-01 00:00:00" as no-match
+      # (#2468).
+      ISO_OPERAND =
+        /\A(\d{4}-\d{2}-\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?\z/
+      private_constant :ISO_OPERAND
 
       def evaluate_operator(operator, value, targets)
         # Case-insensitive views for the string/relational/date operators.
@@ -150,7 +174,10 @@ module Featureflip
         when "SemverLessThanOrEqual"
           targets.any? { |t| compare_semver(value, t, :<=) }
         else
-          false
+          # Unrecognised operator. `nil` — NOT `false` — so the caller can tell
+          # "cannot evaluate" apart from "evaluated, did not match"; only the
+          # latter may be inverted by `negate` (#2262).
+          nil
         end
       end
 
@@ -209,31 +236,87 @@ module Featureflip
       # TryParseDateTime. ISO-8601 strings honor any timezone offset; a string
       # without an offset is assumed UTC. A bare integer is treated as Unix time
       # in seconds. Returns nil when the input parses as neither.
+      # DateTimeOffset.MinValue / MaxValue as unix seconds -- the exact bounds the
+      # engine's FromUnixTimeSeconds accepts before throwing (#2432).
+      MIN_UNIX_SECONDS = -62_135_596_800
+      MAX_UNIX_SECONDS = 253_402_300_799
+
+      # Rewrites an accepted ISO operand into the strict extended form Time.iso8601
+      # parses: "T" separator, seconds present, offset spelled "+HH:MM" or "Z".
+      # Returns nil when the operand is not an accepted ISO shape.
+      def canonicalize_iso(s)
+        m = ISO_OPERAND.match(s)
+        return nil if m.nil?
+
+        date, hh, mm, ss, frac, off = m.captures
+        return "#{date}T00:00:00Z" if hh.nil?
+
+        # The engine's DateTimeOffset.TryParse rejects hour 24 outright rather than
+        # rolling it over to 00:00 the next day, which is what Time.iso8601 does.
+        return nil if hh >= "24"
+
+        ss ||= "00"
+        off =
+          if off.nil? then "Z"
+          elsif off.length == 5 && off != "Z" then "#{off[0, 3]}:#{off[3, 2]}"
+          else off
+          end
+        "#{date}T#{hh}:#{mm}:#{ss}#{frac}#{off}"
+      end
+
       def parse_datetime(value)
-        s = value.to_s.strip
-
-        begin
-          # `Time.iso8601` honors offsets/"Z" but raises on a no-offset string;
-          # append the missing time/offset to assume midnight UTC for bare dates
-          # and UTC for offset-less date-times (mirroring DateTimeOffset.TryParse
-          # with AssumeUniversal).
-          iso =
-            if s.match?(ISO_DATE_ONLY)
-              "#{s}T00:00:00Z"
-            elsif s.match?(ISO_NO_OFFSET)
-              "#{s}Z"
-            else
-              s
-            end
-          return Time.iso8601(iso).utc
-        rescue ArgumentError
-          # Fall through to the Unix-seconds fallback.
+        s = value.to_s
+        # Trim exactly the engine's whitespace class, then reject anything still
+        # carrying a character no operand may contain.
+        s = s.gsub(/\A[#{Regexp.escape(OPERAND_WHITESPACE)}]+|[#{Regexp.escape(OPERAND_WHITESPACE)}]+\z/, "")
+        return nil if s.empty? || s.match?(FORBIDDEN_OPERAND_CHAR)
+
+        iso = canonicalize_iso(s)
+        if iso
+          begin
+            # Offset-less forms were canonicalized to an explicit "Z", mirroring
+            # DateTimeOffset.TryParse with AssumeUniversal.
+            return Time.iso8601(iso).utc
+          rescue ArgumentError
+            # A syntactically-valid but non-existent date (e.g. 2024-02-31) --
+            # fall through to the Unix-seconds fallback, which will also reject it.
+          end
         end
 
         # Integer fallback: treat a bare integer as Unix time in seconds.
-        if s.match?(/\A-?\d+\z/)
+        #
+        # Out-of-range seconds match NOTHING rather than resolving to a far-future
+        # instant: the engine's FromUnixTimeSeconds throws outside DateTimeOffset's
+        # range and TryParseDateTime returns false. Ruby's Time has a far wider range
+        # and would happily accept the value, so the bound has to be explicit. The
+        # case that matters in practice is a MILLISECONDS timestamp pasted where
+        # seconds belong, which would otherwise land in the year 55829 and satisfy
+        # every `After` comparison (#2432).
+        #
+        # The sign class matches the engine's `long.TryParse` with
+        # `NumberStyles.Integer` (`AllowLeadingWhite | AllowTrailingWhite |
+        # AllowLeadingSign`), so a leading "+" is accepted deliberately rather than
+        # incidentally, and `Integer()` reads it the same way. Omitting it made "+5"
+        # an unparseable string matching NOTHING here while the engine and four other
+        # SDKs read it as five seconds past the epoch (#2458).
+        #
+        # The whitespace flags now match too: the trim above is exactly
+        # `AllowLeadingWhite`/`AllowTrailingWhite`'s class, and anything outside it
+        # was already rejected by FORBIDDEN_OPERAND_CHAR (#2468).
+        if s.match?(/\A[+-]?\d+\z/)
           begin
-            return Time.at(Integer(s)).utc
+            # Base 10 EXPLICITLY. Bare `Integer(s)` honours Ruby's literal base
+            # prefixes, so a leading zero means OCTAL: "0500" became 320 rather than
+            # 500, and "0800" raised ArgumentError (8 is not an octal digit) and
+            # matched nothing at all. Every other implementation parses base 10 --
+            # the engine's `long.TryParse`, go's `ParseInt(s, 10, 64)`, java's
+            # `Long.parseLong`, python's `int()`, php's `(int)` cast and js's
+            # `Number()` -- so ruby was alone in reading a zero-padded unix timestamp
+            # as a different instant. Pinned by `c-date-unix-leading-zero-*` (#2458).
+            seconds = Integer(s, 10)
+            return nil if seconds < MIN_UNIX_SECONDS || seconds > MAX_UNIX_SECONDS
+
+            return Time.at(seconds).utc
           rescue RangeError, ArgumentError
             return nil
           end

data/lib/featureflip/events/event_processor.rb

@@ -1,38 +1,75 @@
 module Featureflip
   module Events
     class EventProcessor
-      def initialize(http_client, flush_interval: 30, flush_batch_size: 100)
+      # Upper bound on buffered events.
+      #
+      # Only reachable once #flush starts putting batches back faster than they drain --
+      # i.e. a sustained outage of the events endpoint. Past the bound the OLDEST events
+      # are shed, which caps memory and keeps the freshest analytics. It also means a long
+      # outage sheds the stale re-queued batches rather than starving new events, so the
+      # SDK degrades to the old drop-on-failure behaviour instead of hoarding data it
+      # cannot send.
+      DEFAULT_MAX_QUEUE_SIZE = 10_000
+
+      def initialize(http_client, flush_interval: 30, flush_batch_size: 100,
+                     max_queue_size: DEFAULT_MAX_QUEUE_SIZE, logger: nil)
         @http_client = http_client
         @flush_interval = flush_interval
-        @flush_batch_size = flush_batch_size
+        # Clamped to at least 1: #flush drains @flush_batch_size events per pass and stops
+        # when the queue is empty, so a non-positive size would shift nothing off a
+        # non-empty queue and spin forever. Config#validate! already rejects such values,
+        # but this class is constructed directly too.
+        @flush_batch_size = flush_batch_size.to_i.positive? ? flush_batch_size.to_i : 1
+        @max_queue_size = max_queue_size.to_i.positive? ? max_queue_size.to_i : DEFAULT_MAX_QUEUE_SIZE
+        @logger = logger
         @queue = []
         @mutex = Mutex.new
         @stop_flag = false
+        @stopped = false
         @thread = nil
+
+        # Monotonic instant before which the batch-size trigger must not start another
+        # flush, and a latch held while a size-triggered flush is in flight. Both exist to
+        # stop a re-queued batch from turning every subsequent event into another request
+        # — see #auto_flush.
+        @next_auto_flush_at = 0.0
+        @auto_flush_in_flight = false
       end
 
       def queue_event(event)
-        should_flush = false
+        dropped = 0
         @mutex.synchronize do
+          # After #stop nothing will flush again, so buffering here would only leak.
+          return if @stopped
+
           @queue << event
-          should_flush = @queue.length >= @flush_batch_size
+          dropped = trim_to_bound
         end
-        flush if should_flush
+
+        warn_overflow(dropped)
+        auto_flush
       end
 
+      # Drains the queue a batch at a time, one request per batch.
+      #
+      # This used to post the WHOLE queue in a single request, which was harmless while a
+      # failure emptied the queue: it never grew far past @flush_batch_size. Re-queuing
+      # failures (#2456) is what changed that — after a sustained outage the queue can sit
+      # at its 10,000-event bound, and posting all of that at once risks a body the server
+      # rejects outright. A 413 is non-retryable, so the entire backlog would be dropped by
+      # the very path added to preserve it.
       def flush
-        events_to_send = nil
-        @mutex.synchronize do
-          return if @queue.empty?
-          events_to_send = @queue.dup
-          @queue.clear
-        end
+        loop do
+          batch = drain_batch
+          return if batch.empty?
 
-        return unless events_to_send&.any?
-
-        @http_client.post_events(events_to_send)
-      rescue StandardError
-        # Events are best-effort — drop on failure
+          # False means the batch went back on the queue, and it is at the HEAD of the very
+          # queue this loop drains — carrying on would re-send it immediately and spin for
+          # as long as the endpoint stayed down. A dropped batch returns true instead: the
+          # queue has shrunk, so the loop still terminates, and one poison batch must not
+          # block the backlog behind it.
+          return unless send_batch(batch)
+        end
       end
 
       def start
@@ -42,10 +79,15 @@ module Featureflip
           until @stop_flag
             sleep(1)
             elapsed += 1
-            queue_size = @mutex.synchronize { @queue.length }
-            if elapsed >= @flush_interval || queue_size >= @flush_batch_size
+            next if @stop_flag
+
+            if elapsed >= @flush_interval
+              # The interval tick is the retry vehicle for a re-queued batch, so it is
+              # deliberately NOT subject to the size trigger's backoff gate.
+              elapsed = 0
+              flush
+            elsif auto_flush
               elapsed = 0
-              flush unless @stop_flag
             end
           end
         end
@@ -56,7 +98,162 @@ module Featureflip
         @thread&.wakeup rescue nil
         @thread&.join(5)
         @thread = nil
+
+        # Closed BEFORE the final flush so a failure there is dropped rather than
+        # re-queued: nothing will flush again, and retrying until the queue drains would
+        # hang shutdown for as long as the endpoint stayed down. One attempt, then let go.
+        @mutex.synchronize { @stopped = true }
         flush
+        @mutex.synchronize { @queue.clear }
+      end
+
+      private
+
+      # Batch-size-triggered flush. Returns true only if it actually sent.
+      #
+      # A re-queued batch leaves the queue at or above @flush_batch_size, so without a gate
+      # every subsequent event would trigger another flush — turning a failing endpoint
+      # into one request per evaluation, which is worse for the server than the dropping
+      # this replaced. Two guards, and both are load-bearing:
+      #
+      #   * the backoff gate suppresses the size trigger for one flush interval after a
+      #     retryable failure, leaving the background thread's interval tick as the retry
+      #     vehicle;
+      #   * the in-flight latch covers what the gate cannot, because the gate is only armed
+      #     once a flush has already FAILED and the size trigger fires again long before
+      #     the first round-trip returns. Without it a tight loop of events starts a pile
+      #     of concurrent flushes.
+      #
+      # An explicit #flush (the public API, and the interval tick) bypasses both: the
+      # caller asked for a send.
+      def auto_flush
+        return false unless @mutex.synchronize { claim_size_trigger }
+
+        begin
+          flush
+        ensure
+          @mutex.synchronize { @auto_flush_in_flight = false }
+        end
+        true
+      end
+
+      # Whether a size-triggered flush may start, claiming the latch if so.
+      # Caller holds @mutex.
+      def claim_size_trigger
+        return false if @stopped
+        return false if @auto_flush_in_flight
+        return false if @queue.length < @flush_batch_size
+        return false if monotonic_now < @next_auto_flush_at
+
+        @auto_flush_in_flight = true
+      end
+
+      # Never called with @mutex held: the POST blocks for as long as the endpoint takes to
+      # answer — and Http::Client sleeps a second before its own single inline retry — so
+      # the background thread and every queue_event caller would block behind it.
+      # Sends one batch. Returns true if #flush may go on to the next one — see the comment
+      # at its call site for why a re-queued batch must stop the drain.
+      def send_batch(events)
+        @http_client.post_events(events)
+        @mutex.synchronize { @next_auto_flush_at = 0.0 }
+        true
+      rescue StandardError => e
+        unless retryable_failure?(e)
+          @logger&.warn(
+            "Featureflip: dropped #{events.length} analytics event(s) the events endpoint " \
+            "rejected (#{e.class}: #{e.message}); the failure is not retryable"
+          )
+          return true
+        end
+
+        dropped = requeue(events)
+        # Armed here rather than at the first attempt, so the interval is counted from the
+        # moment post_events' inline retry finally gave up.
+        @mutex.synchronize { @next_auto_flush_at = monotonic_now + @flush_interval }
+
+        if dropped.nil?
+          @logger&.warn(
+            "Featureflip: dropped #{events.length} analytics event(s) " \
+            "(#{e.class}: #{e.message}); the processor is shutting down and will not flush again"
+          )
+        else
+          @logger&.warn(
+            "Featureflip: failed to send #{events.length} analytics event(s) " \
+            "(#{e.class}: #{e.message}); re-queued for the next flush"
+          )
+          warn_overflow(dropped)
+        end
+
+        false
+      end
+
+      # Whether the same batch could succeed if it were sent again.
+      #
+      # For an HTTP answer the status decides: any 5xx — the production edge answers this
+      # endpoint with a 503 at a low but constant rate (#2456) — and 429, where the server
+      # is explicitly asking us to come back later. Anything else will fail identically next
+      # time: 401/403 means the SDK key was rejected, 400 means the body is malformed, and
+      # retrying either forever would pin the queue at its bound and starve every later
+      # event.
+      #
+      # Everything that is NOT an HTTP answer is treated as transient. A transport fault
+      # (connection reset, DNS, TLS) or a timeout carries no status at all and is exactly
+      # the kind of failure a later flush gets past, so the default has to be "keep it"
+      # rather than "not a 5xx, therefore permanent".
+      def retryable_failure?(error)
+        return error.status >= 500 || error.status == 429 if error.is_a?(Featureflip::HttpStatusError)
+
+        true
+      end
+
+      # Takes up to @flush_batch_size of the OLDEST events, leaving the rest queued.
+      def drain_batch
+        @mutex.synchronize do
+          return [] if @queue.empty?
+
+          @queue.shift([@flush_batch_size, @queue.length].min)
+        end
+      end
+
+      # Puts a batch that failed to send back at the FRONT of the queue, so the next flush
+      # retries it ahead of newer events and rough chronological order survives.
+      #
+      # Returns how many events were shed to stay within the bound — or nil if it refused
+      # the batch entirely because #stop has closed the queue. The caller needs to tell
+      # those apart: "re-queued for the next flush" is a lie once there will be no next
+      # flush, and this is the branch a shutdown during an outage takes.
+      def requeue(events)
+        @mutex.synchronize do
+          return nil if @stopped
+
+          @queue.unshift(*events)
+          trim_to_bound
+        end
+      end
+
+      # Sheds oldest-first until the queue fits the bound, returning how many went.
+      # Caller holds @mutex.
+      def trim_to_bound
+        overflow = @queue.length - @max_queue_size
+        return 0 if overflow <= 0
+
+        @queue.shift(overflow)
+        overflow
+      end
+
+      def warn_overflow(dropped)
+        return if dropped.zero?
+
+        @logger&.warn(
+          "Featureflip: event queue is full (#{@max_queue_size}); " \
+          "dropped #{dropped} of the oldest analytics event(s)"
+        )
+      end
+
+      # Wall-clock time can jump backwards (NTP, a suspended host); the backoff gate must
+      # not be extended or skipped by that.
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end
     end
   end

data/lib/featureflip/http/client.rb

@@ -20,18 +20,37 @@ module Featureflip
       # 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 = drop_unevaluable((data["flags"] || []).map { |f| parse_flag(f) }, "flag") do |flag|
+          unevaluable_flag_reason(flag)
+        end
+        segments = drop_unevaluable((data["segments"] || []).map { |s| parse_segment(s) }, "segment") do |segment|
+          unevaluable_segment_reason(segment)
+        end
         [flags, segments]
       end
 
       def get_flag(key)
         response = request(:get, "/v1/sdk/flags/#{key}")
-        parse_flag(JSON.parse(response.body))
+        flag = parse_flag(JSON.parse(response.body))
+
+        # An unevaluable enum drops the flag rather than upserting it (#2402). For a
+        # delta whose whole scope is one flag that means leaving the store's previous
+        # copy alone: replacing it with one this build would mis-evaluate is the outcome
+        # the drop exists to prevent, and FLAG_NOT_FOUND is the honest answer if there
+        # was no previous copy.
+        reason = unevaluable_flag_reason(flag)
+        raise UnevaluableEntityError, "flag #{key.inspect}: #{reason}" if reason
+
+        flag
       end
 
       def post_events(events)
-        request(:post, "/v1/sdk/events", { events: events })
+        # The one caller that retries inline. EventProcessor#flush drains the queue before
+        # sending, so a batch only survives a failure because the processor puts it back --
+        # this absorbs a single transient 5xx before that machinery is needed, which keeps
+        # the common blip off the re-queue path entirely. The processor's backoff gate is
+        # measured from the moment this finally gives up, not from the first attempt.
+        request(:post, "/v1/sdk/events", { events: events }, retry_server_errors: true)
       end
 
       def close
@@ -40,7 +59,13 @@ module Featureflip
 
       private
 
-      def request(method, path, body = nil, retries: 1)
+      # retry_server_errors: retry once on a 5xx. Off by default — the poller re-fetches
+      # every poll_interval and the streaming source reconnects with backoff, so for flag
+      # reads an inner retry buys nothing and doubles request volume against a dependency
+      # that is already failing (it also blocked for a second inside the init_timeout
+      # budget on cold start). eval-api answers 503 when it cannot reach the Management
+      # API, which is exactly the status this used to trip on.
+      def request(method, path, body = nil, retries: 1, retry_server_errors: false)
         uri = URI("#{@base_url}#{path}")
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = uri.scheme == "https"
@@ -62,13 +87,16 @@ module Featureflip
 
         response = http.request(req)
 
-        if response.is_a?(Net::HTTPServerError) && retries > 0
+        if retry_server_errors && response.is_a?(Net::HTTPServerError) && retries > 0
           sleep(1)
-          return request(method, path, body, retries: retries - 1)
+          return request(method, path, body, retries: retries - 1, retry_server_errors: retry_server_errors)
         end
 
         unless response.is_a?(Net::HTTPSuccess)
-          raise Featureflip::Error, "HTTP #{response.code}: #{path}"
+          # HttpStatusError, not a bare Error: the events flush branches on the status to
+          # decide whether the batch is worth keeping (#2456). Same message and same
+          # ancestry, so nothing that rescues Featureflip::Error changes behaviour.
+          raise HttpStatusError.new(response.code.to_i, path)
         end
 
         response
@@ -76,7 +104,7 @@ module Featureflip
              Net::OpenTimeout, Net::ReadTimeout => e
         raise if retries <= 0
         sleep(1)
-        request(method, path, body, retries: retries - 1)
+        request(method, path, body, retries: retries - 1, retry_server_errors: retry_server_errors)
       end
 
       # Enum fields are strings on the wire. Ruby keeps whatever it is handed and the
@@ -165,6 +193,88 @@ module Featureflip
           condition_logic: require_enum_string!(data["conditionLogic"], "segment.conditionLogic") || "And"
         )
       end
+
+      # Entity-level drop for enum values this SDK build cannot evaluate (#2402).
+      #
+      # `serve.type` and `conditionLogic` are the two enums that are BOTH carried on the
+      # wire as strings AND consulted by the evaluator, and each dispatches on a two-way
+      # branch with no third arm:
+      #
+      #   serve.type == "Fixed" ... else ROLLOUT
+      #   logic      == "And"   ... else ANY (OR)
+      #
+      # So an unrecognised value does not fail — it takes the ELSE arm. A segment
+      # carrying conditionLogic "Xor" evaluates as OR, so a segment meant to require ALL
+      # of its conditions matches ANY of them: the rule fails OPEN and over-targets.
+      #
+      # Neither obvious fix works. Tolerating the value — as an unknown flag.type is
+      # tolerated — IS that silent mis-evaluation; flag.type is safe to tolerate only
+      # because nothing evaluates it. Raising MalformedPayloadError would discard the
+      # whole payload, so one additive server change takes down every flag on a pinned
+      # client (the #2372/#2395 outage shape).
+      #
+      # So the containing entity goes instead. Dropping a segment leaves rules pointing
+      # at it dangling, which is safe: Evaluation::Evaluator already treats an
+      # unresolvable segment_key as no-match (#1459), so the cascade fails CLOSED. The
+      # engine-generated `f-segment-unresolvable` golden vector pins that.
+      #
+      # Scoped deliberately to a NON-EMPTY unrecognised value. An absent field already
+      # defaults to "And" above, and the missing-required-field axis is a separate
+      # concern that the SDKs deliberately disagree on; checking only values that are
+      # present and unrecognised keeps this change purely additive.
+      SERVE_TYPES = ["Fixed", "Rollout"].freeze
+      CONDITION_LOGIC = ["And", "Or"].freeze
+
+      def drop_unevaluable(entities, kind)
+        entities.reject do |entity|
+          reason = yield(entity)
+          next false unless reason
+
+          @config.logger&.warn(
+            "Featureflip: dropping #{kind} #{entity.key.inspect}: #{reason}. This SDK " \
+            "version may be older than the flag configuration; the rest of the " \
+            "configuration was applied."
+          )
+          true
+        end
+      end
+
+      # Why this flag cannot be evaluated, or nil if it can. A reason rather than a
+      # boolean so the diagnostic can name the field and the value actually received.
+      def unevaluable_flag_reason(flag)
+        reason = unevaluable_serve_reason(flag.fallthrough, "fallthrough")
+        return reason if reason
+
+        (flag.rules || []).each do |rule|
+          reason = unevaluable_serve_reason(rule.serve, "rule[#{rule.id}].serve")
+          return reason if reason
+
+          (rule.condition_groups || []).each do |group|
+            next if group.operator.nil? || group.operator.empty?
+            next if CONDITION_LOGIC.include?(group.operator)
+
+            return "rule[#{rule.id}].conditionGroup.operator #{group.operator.inspect} " \
+                   "is not a condition logic this SDK version understands"
+          end
+        end
+
+        nil
+      end
+
+      # Why this segment cannot be evaluated, or nil if it can.
+      def unevaluable_segment_reason(segment)
+        logic = segment.condition_logic
+        return nil if logic.nil? || logic.empty? || CONDITION_LOGIC.include?(logic)
+
+        "conditionLogic #{logic.inspect} is not a condition logic this SDK version understands"
+      end
+
+      def unevaluable_serve_reason(serve, path)
+        type = serve&.type
+        return nil if type.nil? || type.empty? || SERVE_TYPES.include?(type)
+
+        "#{path}.type #{type.inspect} is not a serve type this SDK version understands"
+      end
     end
   end
 end

data/lib/featureflip/shared_core.rb

@@ -241,25 +241,29 @@ module Featureflip
       return unless @event_processor
 
       context = normalize_context(context)
-      @event_processor.queue_event({
+      @event_processor.queue_event(compact_event({
         type: "Custom",
         flagKey: event_key,
-        userId: context["user_id"]&.to_s,
-        metadata: metadata || {},
+        userId: resolve_event_user_id(context),
+        metadata: metadata,
         timestamp: Time.now.utc.iso8601
-      })
+      }))
     end
 
     def identify(context)
       return unless @event_processor
 
       context = normalize_context(context)
-      @event_processor.queue_event({
+      # Strip both identity spellings so the id is carried once, at the top
+      # level, and not duplicated inside the attribute bag.
+      attributes = context.reject { |k, _| IDENTITY_KEYS.include?(k) }
+      @event_processor.queue_event(compact_event({
         type: "Identify",
         flagKey: "$identify",
-        userId: context["user_id"]&.to_s,
+        userId: resolve_event_user_id(context),
+        metadata: attributes,
         timestamp: Time.now.utc.iso8601
-      })
+      }))
     end
 
     def flush
@@ -382,7 +386,10 @@ module Featureflip
       @event_processor = Events::EventProcessor.new(
         @http_client,
         flush_interval: @config.flush_interval,
-        flush_batch_size: @config.flush_batch_size
+        flush_batch_size: @config.flush_batch_size,
+        # A dropped or re-queued batch must be visible: this fix keeps analytics that the
+        # edge briefly rejects, and it must not also hide the rejections themselves.
+        logger: @config.logger
       )
       @event_processor.start
     end
@@ -417,16 +424,43 @@ module Featureflip
       context.transform_keys(&:to_s)
     end
 
+    # Both spellings of the identity are accepted on an event context; the
+    # canonical +user_id+ wins when a caller supplies both. The evaluator
+    # already aliases these for bucketing, so events have to as well or an
+    # alias caller gets every event attributed to nil.
+    IDENTITY_KEYS = %w[user_id userId].freeze
+
+    def resolve_event_user_id(context)
+      raw = context["user_id"]
+      raw = context["userId"] if raw.nil?
+      raw&.to_s
+    end
+
+    # +userId+ and +metadata+ are optional on the wire. Omit them rather than
+    # sending nulls or empty bags, matching the other SDKs.
+    #
+    # +metadata+ is caller-supplied and untyped, so the emptiness check is
+    # guarded: a caller passing a non-collection must not take a NoMethodError
+    # into their request path just to record an analytics event.
+    def compact_event(event)
+      event.delete(:userId) if event[:userId].nil?
+      metadata = event[:metadata]
+      if metadata.nil? || (metadata.respond_to?(:empty?) && metadata.empty?)
+        event.delete(:metadata)
+      end
+      event
+    end
+
     def record_evaluation(key, context, variation_key)
       return unless @event_processor
 
-      @event_processor.queue_event({
+      @event_processor.queue_event(compact_event({
         type: "Evaluation",
         flagKey: key,
-        userId: context["user_id"]&.to_s,
+        userId: resolve_event_user_id(context),
         variation: variation_key,
         timestamp: Time.now.utc.iso8601
-      })
+      }))
     end
 
     # Fire the registered evaluation inspectors. Called once per variation call

data/lib/featureflip/version.rb

@@ -1,3 +1,3 @@
 module Featureflip
-  VERSION = "2.5.0"
+  VERSION = "2.6.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureflip
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.1
 platform: ruby
 authors:
 - Featureflip
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-20 00:00:00.000000000 Z
+date: 2026-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger