featureflip 2.11.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dbbc4e1eefae9adf8a818fc31905e674ee68369be22f6d558f1838604a34fba
-  data.tar.gz: 91ddda08b1eb8015d297c4a6206d8df48704cde620908634bdc7c5415b6e3cb4
+  metadata.gz: f9ade6e604108bf5c72e9b0d69dee554ef6c929004db80b56e4d184980de4ee1
+  data.tar.gz: 32c424cf3af497320ad75dc8f23baf336b086f3e8bdf867da20e8e7ce4f96e70
 SHA512:
-  metadata.gz: 1c77f14b1245ebd4453d878c41fbadbea5051cee8b86eb5a9aed6fb210714b71275792b19cf571e62ccacce985babf303db5eeb81875fd6a18009bb169ef5506
-  data.tar.gz: 0ea6aba2d012d330c976e2fee16be73aee7d3ec1392a7bc0677147b2e1d7bac1a33b7048b59afaad82fd72339e984421ddb358339bedb220bacb66b8fa572e55
+  metadata.gz: 5e5d545c1410cac76b7603008f9708a40e6c257e82e8142b1d799fcfc2b5475500072e764a6828b43300fade2cbede2936b82bf1e3e043131606317600ea2985
+  data.tar.gz: b8727a3ddf735c16c4d0094472721ba2ad53fb5bca323024a7d3291b993730efb583cc1683375aea9ba8d3235b523dac252ddac1f82fcc0799718d49337b5065

data/lib/featureflip/evaluation/canonical_number.rb

@@ -0,0 +1,53 @@
+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 with no fractional part keeps its exact integer digits (like the
+      # engine's raw integer text); anything else goes through Float (#4236).
+      def self.format_big_decimal(d)
+        return format(d.to_f) unless d.finite?
+        return d.to_i.to_s if 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
@@ -579,7 +579,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.12.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureflip
 version: !ruby/object:Gem::Version
-  version: 2.11.0
+  version: 2.12.0
 platform: ruby
 authors:
 - Featureflip
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-22 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