featureflip 2.5.1 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a41a0e3edb8d4325e4a0784930973f07ad8339e7b25b127f076bc7cfade0d948
-  data.tar.gz: 6ceb86141220f142710e6a0937af742270c61961ff87f583a2d727bab1c6ee65
+  metadata.gz: 3d0798d6f9dde45580a5345467cfcbc108b01a0bda1ed9c0224a6e58305ec9bd
+  data.tar.gz: d7a7ceca0d72477e0987ee83b0af3bdcee069f47add6ecc89a42bb7c9cb635e4
 SHA512:
-  metadata.gz: 013af1bacae587f2dd832bd7004ac4a94a45e8d635c64204d8ea892d4e62c80112d07856856d097f03393f4bbf7c3aef7d54c378672db9c61623d9053b8e3e3b
-  data.tar.gz: 822537c99bfdd30d8f2f4b16b9b8592d2cd23fdaccaf2cea0333fccdf68f0998877bf124da0060ec63abc0fb347f6506ad10f0fc235d8f22291de50a68f20a33
+  metadata.gz: 2546ac239e8b8c0b120caa1d8286ad9a58e4fe23900a58cb63343ad469e9e324548ebac72ea194c102c023e5de2ef2e88fd344c80d15beb49dfc18803a3bd711
+  data.tar.gz: 6393ec68c36a42813a537fa699e9801132606d273264c142b8d75082c0fc7d260160b27aac53306d49a14bd2d895de2da57e8284690c8affb031076a76500a47

data/lib/featureflip/data_source/streaming.rb

@@ -195,11 +195,27 @@ module Featureflip
         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.
+      # Capped exponential backoff, jittered at every level. failures == 0 means a
+      # healthy stream just closed cleanly; the jitter band's lower bound keeps the
+      # base floor in force so we don't busy-loop.
+      #
+      # Jittering the FIRST reconnect is load-bearing, not cosmetic: the drops this
+      # absorbs are fleet-wide — one edge event severs every stream at once (#2457)
+      # — so every client re-enters here at failures == 0 together. A constant there
+      # replayed the drop's own synchronisation as a reconnect spike one base delay
+      # later (#2508).
       def backoff_delay(failures)
         exponent = failures <= 0 ? 0 : failures - 1
-        [RECONNECT_BASE_DELAY_SECONDS * (2**exponent), MAX_BACKOFF_SECONDS].min
+        with_jitter([RECONNECT_BASE_DELAY_SECONDS * (2**exponent), MAX_BACKOFF_SECONDS].min)
+      end
+
+      # Returns a value in [d/2, d] to de-correlate reconnects across many SDK
+      # instances (thundering-herd avoidance after a shared outage).
+      def with_jitter(delay)
+        return delay if delay <= 0
+
+        half = delay / 2.0
+        half + (rand * half)
       end
 
       # Sleep for `seconds`, but return immediately if stop() fires — so a pending
@@ -234,6 +250,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

@@ -74,16 +74,36 @@ 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
+
+      # Length of each month in a non-leap year, indexed 1..12. Index 0 is unused padding.
+      DAYS_IN_MONTH = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31].freeze
+      private_constant :DAYS_IN_MONTH
 
       def evaluate_operator(operator, value, targets)
         # Case-insensitive views for the string/relational/date operators.
@@ -216,35 +236,153 @@ module Featureflip
         left.send(op, right)
       end
 
+      # 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
+
+      # Whether +date+ -- always "YYYY-MM-DD", since only canonicalize_iso calls this --
+      # names a day that exists.
+      #
+      # ISO_OPERAND matches the SHAPE of a calendar date and a character class cannot
+      # express "is a real day", so "2024-02-30", "2023-02-29" and "2024-04-31" all pass
+      # the grammar. The engine, csharp, go, python and java then reject them at parse;
+      # ruby, js and php ROLLED THEM OVER into the 1st of the following month, so one
+      # saved rule served different variations to two users purely by which SDK their
+      # service ran (#2491).
+      #
+      # Hand-rolled rather than delegated to Date.valid_date?, which applies the Italian
+      # calendar reform by DEFAULT and so rejects 1582-10-05..14 -- dates the engine
+      # resolves normally. Passing Date::GREGORIAN would fix that, but computing the
+      # arithmetic identically in ruby, js and php is what keeps the accepted set a
+      # property of THIS contract rather than of three separate calendars.
+      #
+      # Proleptic Gregorian, matching the engine: the leap rule applies at every year
+      # rather than from a reform date onward.
+      def real_calendar_day?(date)
+        year = date[0, 4].to_i
+        month = date[5, 2].to_i
+        day = date[8, 2].to_i
+
+        # Month 0 and day 0 are the shapes only php mishandled, rolling each BACKWARDS
+        # into the previous year ("2024-00-01" -> 2023-12-01, "2024-01-00" -> 2023-12-31).
+        return false if month < 1 || month > 12 || day < 1
+
+        leap_day = month == 2 && year % 4 == 0 && (year % 100 != 0 || year % 400 == 0) ? 1 : 0
+        day <= DAYS_IN_MONTH[month] + leap_day
+      end
+
+      # 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
+
+        # Checked on the WRITTEN date, before any offset is applied. Validating the
+        # resolved UTC components instead would accept "2024-02-30T00:00:00+05:00",
+        # which lands on 2024-02-29T19:00Z -- a date that does exist.
+        return nil unless real_calendar_day?(date)
+
+        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
+
       # Parses a date-time to a UTC `Time`, mirroring the engine's
       # 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.
       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.
+            t = Time.iso8601(iso).utc
+
+            # The SAME range the integer branch below enforces, applied to the
+            # RESOLVED instant. The engine parses with DateTimeOffset.TryParse, so its
+            # accepted set is bounded by DateTimeOffset's range and it returns false
+            # outside it; ruby, js, php, go and java all resolve past both ends --
+            # year 0 to a real instant, and a 4-digit year plus an offset to one
+            # beyond either bound (#2500).
+            #
+            # Checked on the RESOLVED instant, deliberately unlike the WRITTEN-triple
+            # check in real_calendar_day?. The two answer different questions: whether
+            # the operand names a real DAY is a property of what was written
+            # ("2024-02-30T00:00:00+05:00" lands on a real UTC day but names none),
+            # whereas whether it is REPRESENTABLE is a property of what it resolves to
+            # -- the offset is exactly what carries "0001-01-01T00:00:00+05:00" under
+            # the floor and "9999-12-31T23:59:59-05:00" over the ceiling.
+            #
+            # to_i floors, matching the other SDKs: a fractional second is always a
+            # non-negative addend, so "0000-12-31T23:59:59.5Z" floors to MIN-1 and is
+            # rejected while "0001-01-01T00:00:00.5Z" floors to MIN and is kept.
+            seconds = t.to_i
+            return nil if seconds < MIN_UNIX_SECONDS || seconds > MAX_UNIX_SECONDS
+
+            return t
+          rescue ArgumentError
+            # An unreal day is already gone (real_calendar_day?), so this now only
+            # catches the out-of-range minute and second the grammar's \d{2} still
+            # admits ("00:99", "00:00:99"), which every other SDK rejects too. Falls
+            # through to the Unix-seconds fallback, which rejects a non-integer.
+          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,127 @@
 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
+
+        # Coalescing state for the drain loop. @auto_flush_in_flight above only ever
+        # guarded the SIZE trigger; nothing stopped the background thread's interval
+        # tick, an explicit Client#flush and a size-triggered flush from entering the
+        # loop together. Two concurrent drains mean two request streams against the
+        # endpoint the backoff gate exists to protect — and a success in one clears
+        # the gate a failure in the other has just armed, re-opening the
+        # one-request-per-event behaviour outright (#2477).
+        #
+        # Generation counters rather than a bare flag: a waiter has to be able to
+        # tell "the drain I was waiting for has finished" from "a later drain is
+        # running", or it would sleep through its own completion.
+        @drain_in_flight = false
+        @drain_started = 0
+        @drain_finished = 0
+        @drain_done = ConditionVariable.new
       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.
+      # At most one drain runs at a time. A caller arriving while one is already
+      # going waits for it and returns — it does NOT start its own, and it does NOT
+      # return early, because a caller that asked for a flush is asking for its
+      # events to be sent. This matches the js/node SDKs, whose flush() has always
+      # returned the in-flight promise (#2477).
       def flush
-        events_to_send = nil
-        @mutex.synchronize do
-          return if @queue.empty?
-          events_to_send = @queue.dup
-          @queue.clear
+        mine = @mutex.synchronize do
+          if @drain_in_flight
+            nil
+          else
+            @drain_in_flight = true
+            @drain_started += 1
+          end
         end
 
-        return unless events_to_send&.any?
+        if mine.nil?
+          @mutex.synchronize do
+            waiting_for = @drain_started
+            @drain_done.wait(@mutex) while @drain_finished < waiting_for
+          end
+          return
+        end
 
-        @http_client.post_events(events_to_send)
-      rescue StandardError
-        # Events are best-effort — drop on failure
+        begin
+          drain
+        ensure
+          @mutex.synchronize do
+            @drain_in_flight = false
+            @drain_finished = mine
+            @drain_done.broadcast
+          end
+        end
+      end
+
+      # The drain loop itself, callable when coalescing must be bypassed.
+      # Private: #flush is the public entry point, and #stop reaches this directly.
+      private def drain
+        loop do
+          batch = drain_batch
+          return if batch.empty?
+
+          # 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 +131,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 +150,168 @@ module Featureflip
         @thread&.wakeup rescue nil
         @thread&.join(5)
         @thread = nil
-        flush
+
+        # 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 }
+        # drain, not flush: shutdown must never be the call that gets coalesced
+        # away. If the interval tick's drain happens to be in flight, flush would
+        # wait for it and return, and anything queued after that loop's last look
+        # would be discarded unsent. Two drains overlapping is safe here precisely
+        # because @stopped is already set, so neither can re-queue and there is no
+        # backoff left to disarm.
+        drain
+        @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

@@ -386,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

data/lib/featureflip/version.rb

@@ -1,3 +1,3 @@
 module Featureflip
-  VERSION = "2.5.1"
+  VERSION = "2.7.0"
 end

metadata

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