featureflip 2.10.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33b15e24100b214989443fd146e3b5a4ef29c92ee28f457419c4ef0816e01efa
-  data.tar.gz: f638de9e949664b629c35771bce31f2dff71eb018133eeecc3a1d952ba037992
+  metadata.gz: f9ade6e604108bf5c72e9b0d69dee554ef6c929004db80b56e4d184980de4ee1
+  data.tar.gz: 32c424cf3af497320ad75dc8f23baf336b086f3e8bdf867da20e8e7ce4f96e70
 SHA512:
-  metadata.gz: 0c3da771ddf9cb78f4a73f890d03d178047f78dfdf0a1347a52ca82dd1e3721f79b3249856ea1413068aa924b1f5d9acf9a8c2449b79731134508b9f4701714f
-  data.tar.gz: f73db84108ad650e6812868b217fc3b981ba0cdbc2985de312ef94d2fc88d8fdb2d24cc638a5c24837b3598271f7a49005ed5ba1b9f428778099909042b5457b
+  metadata.gz: 5e5d545c1410cac76b7603008f9708a40e6c257e82e8142b1d799fcfc2b5475500072e764a6828b43300fade2cbede2936b82bf1e3e043131606317600ea2985
+  data.tar.gz: b8727a3ddf735c16c4d0094472721ba2ad53fb5bca323024a7d3291b993730efb583cc1683375aea9ba8d3235b523dac252ddac1f82fcc0799718d49337b5065

data/lib/featureflip/config.rb

@@ -4,6 +4,15 @@ module Featureflip
                   :flush_batch_size, :init_timeout, :connect_timeout, :read_timeout,
                   :max_stream_retries, :send_events, :logger
 
+    # Identifies a library that wraps this SDK, such as the OpenFeature provider. Its
+    # token is sent after the SDK's own in the User-Agent
+    # (`featureflip-ruby/<version> my-wrapper/1.0.0`) so usage through the wrapper can be
+    # counted. Both parts must be valid HTTP tokens; an invalid wrapper is ignored with a
+    # logged warning. wrapper_version may be nil. Leave unset when calling the SDK
+    # directly. Excluded from SharedCore._configs_equal: it identifies the caller rather
+    # than changing behavior.
+    attr_accessor :wrapper_name, :wrapper_version
+
     # Evaluation inspectors -- callables invoked once per variation call with a
     # Models::EvaluationEvent. Always an Array; non-callable entries are dropped
     # on assignment rather than blowing up on the evaluation hot path.
@@ -22,7 +31,9 @@ module Featureflip
       max_stream_retries: 5,
       send_events: true,
       logger: nil,
-      inspectors: nil
+      inspectors: nil,
+      wrapper_name: nil,
+      wrapper_version: nil
     )
       @sdk_key = sdk_key
       @base_url = base_url
@@ -37,6 +48,8 @@ module Featureflip
       @send_events = send_events
       @logger = logger || default_logger
       self.inspectors = inspectors
+      @wrapper_name = wrapper_name
+      @wrapper_version = wrapper_version
 
       validate!
     end
@@ -53,6 +66,13 @@ module Featureflip
       @inspectors = list.select { |i| i.respond_to?(:call) }.freeze
     end
 
+    # The User-Agent for every request: the SDK token, then the wrapper's (#4154). Built
+    # on first use and memoized, so the HTTP client and the stream share one value and an
+    # invalid wrapper is warned about once.
+    def user_agent
+      @user_agent ||= SdkIdentity.user_agent(self)
+    end
+
     def validate!
       finalize!
       validate_positive_fields!

data/lib/featureflip/data_source/streaming.rb

@@ -160,7 +160,9 @@ module Featureflip
         req = Net::HTTP::Get.new(uri.request_uri)
         req["Authorization"] = @sdk_key
         req["Accept"] = "text/event-stream"
-        req["User-Agent"] = "featureflip-ruby/#{Featureflip::VERSION}"
+        # Same memoized value as the HTTP client, so an invalid wrapper is warned about
+        # once rather than on every reconnect.
+        req["User-Agent"] = @config.user_agent
 
         http.request(req) do |response|
           unless response.is_a?(Net::HTTPSuccess)

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/http/client.rb

@@ -83,7 +83,7 @@ module Featureflip
 
         req["Authorization"] = @sdk_key
         req["Content-Type"] = "application/json"
-        req["User-Agent"] = "featureflip-ruby/#{Featureflip::VERSION}"
+        req["User-Agent"] = @config.user_agent
 
         response = http.request(req)
 

data/lib/featureflip/sdk_identity.rb

@@ -0,0 +1,27 @@
+module Featureflip
+  # The User-Agent every request carries so the Evaluation API can count SDK usage by
+  # name and version (#4154, contract in #4138): `featureflip-ruby/<version>`, then the
+  # configured wrapper's token. VERSION is the constant the publish workflow rewrites,
+  # never a second literal (#2141).
+  module SdkIdentity
+    # RFC 9110 product token: tchars.
+    TOKEN = /\A[!#$%&'*+.^_`|~0-9A-Za-z-]+\z/
+
+    def self.user_agent(config)
+      sdk = "featureflip-ruby/#{Featureflip::VERSION}"
+      name = config.wrapper_name
+      return sdk if name.nil? || name.to_s.empty?
+
+      version = config.wrapper_version
+      unless TOKEN.match?(name.to_s) && (version.nil? || TOKEN.match?(version.to_s))
+        # Dropped rather than raised: identity metadata must never stop the client starting.
+        config.logger.warn(
+          "Featureflip: ignoring wrapper '#{name}/#{version}': not a valid User-Agent product token"
+        )
+        return sdk
+      end
+
+      version.nil? ? "#{sdk} #{name}" : "#{sdk} #{name}/#{version}"
+    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
@@ -595,6 +595,8 @@ module Featureflip
       @update_listeners_mutex = Mutex.new
     end
 
+    # wrapper_name/wrapper_version are deliberately excluded: they identify the caller
+    # rather than change behavior (see Config).
     def self._configs_equal(a, b)
       a.base_url == b.base_url &&
         a.streaming == b.streaming &&

data/lib/featureflip/version.rb

@@ -1,3 +1,3 @@
 module Featureflip
-  VERSION = "2.10.0"
+  VERSION = "2.12.0"
 end

data/lib/featureflip.rb

@@ -1,6 +1,7 @@
 require_relative "featureflip/version"
 require_relative "featureflip/errors"
 require_relative "featureflip/config"
+require_relative "featureflip/sdk_identity"
 require_relative "featureflip/models/flag"
 require_relative "featureflip/models/segment"
 require_relative "featureflip/models/evaluation_detail"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureflip
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 2.12.0
 platform: ruby
 authors:
 - Featureflip
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-10 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
@@ -88,6 +90,7 @@ files:
 - lib/featureflip/models/evaluation_event.rb
 - lib/featureflip/models/flag.rb
 - lib/featureflip/models/segment.rb
+- lib/featureflip/sdk_identity.rb
 - lib/featureflip/shared_core.rb
 - lib/featureflip/store/flag_store.rb
 - lib/featureflip/store/update_diff.rb