featureflip 2.11.0 → 2.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dbbc4e1eefae9adf8a818fc31905e674ee68369be22f6d558f1838604a34fba
-  data.tar.gz: 91ddda08b1eb8015d297c4a6206d8df48704cde620908634bdc7c5415b6e3cb4
+  metadata.gz: c41498d43abe3f592e70ef93178a39bbabfc481072cf1862b3a18399ad3972db
+  data.tar.gz: 00b9495f23ece99027e3c03c647616cd240a11338f8376511ac4bbd2ce46e826
 SHA512:
-  metadata.gz: 1c77f14b1245ebd4453d878c41fbadbea5051cee8b86eb5a9aed6fb210714b71275792b19cf571e62ccacce985babf303db5eeb81875fd6a18009bb169ef5506
-  data.tar.gz: 0ea6aba2d012d330c976e2fee16be73aee7d3ec1392a7bc0677147b2e1d7bac1a33b7048b59afaad82fd72339e984421ddb358339bedb220bacb66b8fa572e55
+  metadata.gz: 3c397937ed703003e47e5999a9ffd0cd6004ce0ee02e0b216ba6c99c06dec2b03a37ceb9163b8fba36cc413747782fc13ccd84ed7218e307cd21f92ded5566da
+  data.tar.gz: ca65db25d697572ceae8f048bb5672407639fd9aeebf0bc3e0f691cfd08e3993983d78c80f80ad9997852725ebd319ca0b19c069c455fde3b8b43c4c54f73e41

data/lib/featureflip/evaluation/canonical_number.rb

@@ -0,0 +1,56 @@
+module Featureflip
+  module Evaluation
+    # Canonical spelling of a floating-point rollout bucket value (#4236): the same
+    # text as ECMAScript Number::toString and the Evaluation API's
+    # BucketValueFormatter.CanonicalNumber, so every SDK hashes one number to one
+    # bucket. Used only on the bucket path; condition evaluation is unaffected.
+    module CanonicalNumber
+      # A BigDecimal below 1e21 with no fractional part keeps its exact integer digits (like
+      # the engine's raw integer text); anything else goes through Float (#4236). The 1e21
+      # cap is where ECMAScript spelling turns exponential, and stops BigDecimal("1E+999999999")
+      # expanding to a billion digits per evaluation (#4246). BigDecimal#exponent is n in
+      # 0.ddd * 10**n, so |d| < 1e21 is exponent <= 21.
+      def self.format_big_decimal(d)
+        return format(d.to_f) unless d.finite?
+        return d.to_i.to_s if d.exponent <= 21 && d.frac.zero?
+
+        format(d.to_f)
+      end
+
+      def self.format(x)
+        return "NaN" if x.nan?
+        return (x.positive? ? "Infinity" : "-Infinity") if x.infinite?
+        return "0" if x.zero?
+        return "-" + format(-x) if x.negative?
+
+        # Float#to_s is the shortest round-trip form (e.g. "0.1", "100.25", "1.0e+21").
+        # Kernel.format("%.{p}e", ...) with the first round-tripping p is NOT always
+        # shortest: for 2**-44 the nearest 16-digit decimal does not round-trip but a
+        # neighbour does, so the loop yields 17 digits where ECMAScript yields 16.
+        mantissa, exp10 = x.to_s.split("e")
+        int_part, frac_part = mantissa.split(".")
+        frac_part ||= ""
+        all_digits = int_part + frac_part
+        lead = all_digits.length - all_digits.sub(/\A0+/, "").length
+        lead = all_digits.length - 1 if lead >= all_digits.length
+        exp = exp10.to_i + int_part.length - 1 - lead
+        digits = all_digits[lead..].sub(/0+\z/, "")
+        digits = "0" if digits.empty?
+        k = digits.length
+        n = exp + 1
+
+        if k <= n && n <= 21
+          digits + "0" * (n - k)
+        elsif n.positive? && n <= 21
+          "#{digits[0, n]}.#{digits[n..]}"
+        elsif n > -6 && n <= 0
+          "0." + "0" * -n + digits
+        else
+          e = n - 1
+          head = k > 1 ? "#{digits[0]}.#{digits[1..]}" : digits
+          "#{head}e#{e >= 0 ? '+' : '-'}#{e.abs}"
+        end
+      end
+    end
+  end
+end

data/lib/featureflip/evaluation/evaluator.rb

@@ -1,5 +1,7 @@
 require_relative "condition_evaluator"
 require_relative "bucketing"
+require_relative "canonical_number"
+require_relative "unbucketable_warnings"
 
 module Featureflip
   module Evaluation
@@ -9,8 +11,9 @@ module Featureflip
       # the JS reference implementation; see prerequisite_spec.rb depth test.
       MAX_PREREQUISITE_DEPTH = 10
 
-      def initialize
+      def initialize(logger: nil)
         @condition_evaluator = ConditionEvaluator.new
+        @logger = logger
       end
 
       def evaluate(flag, context, get_segment: nil, all_flags: {})
@@ -63,7 +66,21 @@ module Featureflip
 
           if conditions_match
             variation_key = resolve_serve(rule.serve, context)
+            # A rollout that can't bucket the context doesn't match; fall to the next rule (#4236).
+            if variation_key.nil?
+              warn_unbucketable(flag, rule.id, rule.serve)
+              next
+            end
+
+            # A served key that names no variation is malformed config: report Error (no
+            # rule id) with the served key, like the engine's ServeVariation (#4236).
             variation = flag.get_variation(variation_key)
+            if variation.nil?
+              result = Models::EvaluationDetail.new(value: nil, reason: "Error", variation_key: variation_key)
+              memo[flag.key] = result
+              return result
+            end
+
             result = Models::EvaluationDetail.new(
               value: variation&.value,
               reason: "RuleMatch",
@@ -76,9 +93,18 @@ module Featureflip
         end
 
         variation_key = resolve_serve(flag.fallthrough, context)
+        if variation_key.nil?
+          warn_unbucketable(flag, nil, flag.fallthrough)
+          variation_key = flag.fallthrough.variation || ""
+        end
         variation = flag.get_variation(variation_key)
+        if variation.nil?
+          result = Models::EvaluationDetail.new(value: nil, reason: "Error", variation_key: variation_key)
+          memo[flag.key] = result
+          return result
+        end
         result = Models::EvaluationDetail.new(
-          value: variation&.value,
+          value: variation.value,
           reason: "Fallthrough",
           variation_key: variation_key
         )
@@ -123,14 +149,26 @@ module Featureflip
 
       def off_result(flag, reason:, prerequisite_key: nil)
         variation = flag.get_variation(flag.off_variation)
+        # An off variation the flag doesn't define is malformed config: report Error
+        # (value nil, the key kept), like the engine's ServeVariation (#4236).
+        if variation.nil?
+          return Models::EvaluationDetail.new(value: nil, reason: "Error", variation_key: flag.off_variation)
+        end
+
         Models::EvaluationDetail.new(
-          value: variation&.value,
+          value: variation.value,
           reason: reason,
           variation_key: flag.off_variation,
           prerequisite_key: prerequisite_key
         )
       end
 
+      def warn_unbucketable(flag, rule_id, serve)
+        UnbucketableWarnings.warn(@logger, flag.key, rule_id, serve.bucket_by || "userId")
+      end
+
+      # Returns the variation key to serve, or nil when a Rollout serve can't bucket
+      # the context (see resolve_rollout). A Fixed serve never returns nil.
       def resolve_serve(serve, context)
         if serve.type == "Fixed"
           serve.variation || ""
@@ -145,7 +183,12 @@ module Featureflip
         # Alias "userId" <-> "user_id" for the built-in user identifier
         bucket_value = context["user_id"] if bucket_value.nil? && bucket_by == "userId"
         bucket_value = context["userId"] if bucket_value.nil? && bucket_by == "user_id"
-        bucket_value_str = bucket_value.nil? ? "" : bucket_value.to_s
+        bucket_value_str =
+          if bucket_value.nil? then ""
+          elsif bucket_value.is_a?(Float) then CanonicalNumber.format(bucket_value)
+          elsif defined?(::BigDecimal) && bucket_value.is_a?(::BigDecimal) then CanonicalNumber.format_big_decimal(bucket_value)
+          else bucket_value.to_s
+          end
 
         # A Rollout serve can arrive with no weighted variations -- env-level PercentageRollout
         # has nowhere to store per-variation weights, so the mapper emits type=Rollout with no
@@ -153,14 +196,10 @@ module Featureflip
         # empty key. Mirrors the engine + C#/Java SDK evaluators.
         return serve.variation || "" if (serve.variations || []).empty?
 
-        # Keyless user contexts can't be bucketed. Rather than hashing the empty value
-        # into an arbitrary salt-dependent bucket, serve the control (first) variation
-        # deterministically. The engine assigns a random GUID per eval (spreading
-        # anonymous users over HTTP); local SDK eval is deterministic, so parity is
-        # guaranteed only for keyed contexts (#1457).
-        if bucket_value_str == "" && %w[userId user_id].include?(bucket_by) && !(serve.variations || []).empty?
-          return serve.variations[0].key
-        end
+        # A missing, nil or empty bucket value can't be bucketed: return nil so the caller
+        # skips the rule (or serves the fallthrough's variation) instead of hashing the empty
+        # string into an arbitrary bucket. Whitespace, "0", 0 and false bucket normally (#4236).
+        return nil if bucket_value_str == ""
 
         bucket = Bucketing.compute_bucket(serve.salt || "", bucket_value_str)
 

data/lib/featureflip/evaluation/unbucketable_warnings.rb

@@ -0,0 +1,48 @@
+require "set"
+
+module Featureflip
+  module Evaluation
+    # Process-wide, deduplicated warning for a percentage rollout that was skipped
+    # because the context has no value for its bucket-by attribute (#4236).
+    #
+    # Logs once per (flag key, rule id or "fallthrough", bucket_by). The set is
+    # capped at MAX_KEYS; once full, unseen keys are dropped silently. Only the
+    # flag key, rule id and bucket-by attribute NAME are logged, never a context
+    # value.
+    module UnbucketableWarnings
+      MAX_KEYS = 1000
+
+      @mutex = Mutex.new
+      @seen = Set.new
+
+      class << self
+        def warn(logger, flag_key, rule_id, bucket_by)
+          where = rule_id.nil? ? "fallthrough" : "rule #{rule_id}"
+          key = [flag_key, where, bucket_by]
+
+          @mutex.synchronize do
+            return if @seen.include?(key) || @seen.size >= MAX_KEYS
+
+            @seen.add(key)
+          end
+
+          logger&.warn(
+            "[featureflip] Skipped the percentage rollout in flag \"#{flag_key}\" (#{where}): " \
+            "the context has no value for \"#{bucket_by}\". " \
+            "Pass a stable id in that attribute to include this context in the rollout."
+          )
+        end
+
+        # Number of distinct keys recorded so far.
+        def count
+          @mutex.synchronize { @seen.size }
+        end
+
+        # Clears the dedup set. For tests.
+        def reset
+          @mutex.synchronize { @seen.clear }
+        end
+      end
+    end
+  end
+end

data/lib/featureflip/shared_core.rb

@@ -85,7 +85,7 @@ module Featureflip
       # the "different config" warning.
       @inspectors = config.inspectors || []
       @store = Store::FlagStore.new
-      @evaluator = Evaluation::Evaluator.new
+      @evaluator = Evaluation::Evaluator.new(logger: @config.logger)
       @initialized = false
       @closed = false
       @test_mode = false
@@ -185,7 +185,7 @@ module Featureflip
 
       flag = @store.get_flag(key)
       unless flag
-        record_evaluation(key, context, nil)
+        record_evaluation(key, context, nil, reason: "FlagNotFound")
         notify_inspectors(key, context, default_value, reason: "FlagNotFound")
         return Models::EvaluationDetail.new(value: default_value, reason: "FlagNotFound")
       end
@@ -224,7 +224,10 @@ module Featureflip
         reason = "Error"
       end
 
-      record_evaluation(key, context, result.variation_key)
+      record_evaluation(
+        key, context, result.variation_key,
+        reason: reason, rule_id: result.rule_id, prerequisite_key: result.prerequisite_key
+      )
       notify_inspectors(
         key, context, value,
         reason: reason,
@@ -244,6 +247,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.
+      record_evaluation(key, context, nil, reason: "Error")
       notify_inspectors(key, context, default_value, reason: "Error")
       Models::EvaluationDetail.new(value: default_value, reason: "Error", prerequisite_key: nil)
     end
@@ -521,16 +525,36 @@ module Featureflip
       event
     end
 
-    def record_evaluation(key, context, variation_key)
+    # The kebab-case reason categories the Evaluation event carries (#4268), so
+    # the source of traffic reads the same whichever SDK reported it. The
+    # PascalCase names stay the public EvaluationDetail API; only the event is
+    # translated.
+    WIRE_REASONS = {
+      "RuleMatch" => "rule-match",
+      "Fallthrough" => "fallthrough",
+      "FlagDisabled" => "flag-disabled",
+      "FlagNotFound" => "flag-not-found",
+      "PrerequisiteFailed" => "prerequisite-failed",
+      "Error" => "error"
+    }.freeze
+
+    # +ruleId+ rides only on a rule match: an Error read can still carry the rule
+    # that selected a malformed variation, and that rule did not serve the
+    # traffic. Absent optionals are compacted away so they are omitted, never null.
+    def record_evaluation(key, context, variation_key, reason:, rule_id: nil, prerequisite_key: nil)
       return unless @event_processor
 
-      @event_processor.queue_event(compact_event({
+      event = {
         type: "Evaluation",
         flagKey: key,
         userId: resolve_event_user_id(context),
         variation: variation_key,
-        timestamp: Time.now.utc.iso8601
-      }))
+        timestamp: Time.now.utc.iso8601,
+        prerequisiteKey: prerequisite_key,
+        reason: WIRE_REASONS[reason],
+        ruleId: reason == "RuleMatch" ? rule_id : nil
+      }
+      @event_processor.queue_event(event.compact)
     end
 
     # Fire the registered evaluation inspectors. Called once per variation call
@@ -579,7 +603,7 @@ module Featureflip
       @config = Config.new
       @inspectors = []
       @store = Store::FlagStore.new
-      @evaluator = Evaluation::Evaluator.new
+      @evaluator = Evaluation::Evaluator.new(logger: @config.logger)
       @initialized = true
       @closed = false
       @test_mode = true

data/lib/featureflip/version.rb

@@ -1,3 +1,3 @@
 module Featureflip
-  VERSION = "2.11.0"
+  VERSION = "2.13.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureflip
 version: !ruby/object:Gem::Version
-  version: 2.11.0
+  version: 2.13.0
 platform: ruby
 authors:
 - Featureflip
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -79,8 +79,10 @@ files:
 - lib/featureflip/data_source/streaming.rb
 - lib/featureflip/errors.rb
 - lib/featureflip/evaluation/bucketing.rb
+- lib/featureflip/evaluation/canonical_number.rb
 - lib/featureflip/evaluation/condition_evaluator.rb
 - lib/featureflip/evaluation/evaluator.rb
+- lib/featureflip/evaluation/unbucketable_warnings.rb
 - lib/featureflip/events/event.rb
 - lib/featureflip/events/event_processor.rb
 - lib/featureflip/http/client.rb