toggly 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 750edb3f8314278562443c8e2d1c55342f0cf412660c67be6518b73adb7e391c
-  data.tar.gz: 37e1959bfe363ca29d389c511663f170bac4d8501f3ae5343dcde76a43ced889
+  metadata.gz: 7b199467e0cb56245072bf1b0bda7b00ddf7931be0c87e691dac159287f1304e
+  data.tar.gz: 184d195d8caf6321358d2bda8894f8134d1bd2d5ddc3eca6dfd92c7c7c19595b
 SHA512:
-  metadata.gz: 0ffa45e64fd2517b201de7701c74f0e797bdfbeddc76affc469fe37113e352b99a6024db42c36e9ce13d163f3530e6cc23a17bf770eeedd9f2c22dc3216c30b5
-  data.tar.gz: 4cf489e30d206a5bf9bd92153b865e57ebaf04190909c16559d10e90edfd1a017ef27bed38c6356186102167cf0617111f0f34a950443fb3ce32b50c69d3cb9a
+  metadata.gz: ddfa9d5bcbf04311a427752c3dba07edb52b841e61f8630d6b9beca6d34d34d1c53b3107f7ca1c9a07f73a8d796278ef2296cd0b723d1ed83be2504277e4449b
+  data.tar.gz: 76bf82b4e3e23cdfea1beb0edd735a2be3ae8ce38982c7bfc75dcc00093160666b7372815ea462480590edf7c72dd0ec0b71a2bc11661b0510b8d85c39425c88

data/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-09-04
+
+### Added
+
+- EvalContext fields `claims` and `request` (`userAgent`, `acceptLanguage`,
+  `country`) plus `Toggly::RequestContext` and `Toggly::HttpRequestMapper`
+  (headers → request; country order `cf-ipcountry` → `x-vercel-ip-country` →
+  `cloudfront-viewer-country`).
+- Segment filters: `BrowserFamily`, `BrowserLanguage`, `Country` /
+  `CountryFamily`, `DeviceType`, `OS` / `OperatingSystem` with indexed params
+  and Percentage fail-closed gating.
+- `UserClaims` filter (`Claim` + `Value`).
+- `Microsoft.Percentage`, `Microsoft.TimeWindow`, and `Microsoft.Targeting`
+  aliases; golden fixtures under `docs/filter-parity/fixtures/`.
+
+### Changed
+
+- Sticky percentage hashing now uses Definitions / toggly-eval SHA-256
+  (`featureKey + "\n" + userId`, little-endian uint32 / `0xFFFFFFFF * 100`)
+  instead of FNV-1a. Existing sticky cohorts shift when upgrading from 0.2.x.
+- Unknown filter names fail closed.
+- Percentage missing or `≤0` fails closed (aligned with filter-parity contract).
+
+## [0.2.1] - 2026-09-03
+
+### Changed
+
+- Raise required Ruby version to 3.2+ (matches Gemfile.lock Bundler and CI).
+
 ## [0.2.0] - 2026-08-21
 
 ### Added

data/lib/toggly/context.rb

@@ -1,23 +1,31 @@
 # frozen_string_literal: true
 
 module Toggly
-  # Evaluation context containing user identity, groups, and traits.
+  # Evaluation context containing user identity, groups, claims, request, and traits.
   #
   # @example
   #   context = Toggly::Context.new(
   #     identity: "user-123",
   #     groups: ["beta-testers", "premium"],
-  #     traits: { country: "US", plan: "enterprise" }
+  #     claims: { "role" => "admin" },
+  #     request: Toggly::RequestContext.new(country: "US"),
+  #     traits: { plan: "enterprise" }
   #   )
   class Context
     # @return [String, nil] User identity for percentage rollouts and targeting
-    # identity, groups, traits, and optional entity for ContextProperty filters
-    attr_reader :identity, :groups, :traits, :entity
+    # @return [Array<String>] Audience groups
+    # @return [Hash{String => Object}] Legacy/custom traits
+    # @return [Hash{String => String}] Principal claims for UserClaims filters
+    # @return [RequestContext, nil] HTTP request fields for segment filters
+    # @return [EntityContext, nil] Optional entity for ContextProperty filters
+    attr_reader :identity, :groups, :traits, :claims, :request, :entity
 
-    def initialize(identity: nil, groups: [], traits: {}, entity: nil)
+    def initialize(identity: nil, groups: [], traits: {}, claims: {}, request: nil, entity: nil)
       @identity = identity&.to_s
       @groups = Array(groups).map(&:to_s)
       @traits = normalize_traits(traits)
+      @claims = normalize_claims(claims)
+      @request = coerce_request(request)
       @entity = entity
     end
 
@@ -36,6 +44,33 @@ module Toggly
       new
     end
 
+    # Create from a hash (EvalContext / fixture style).
+    #
+    # @param data [Hash]
+    # @return [Context]
+    def self.from_hash(data)
+      return anonymous unless data.is_a?(Hash)
+
+      entity_data = data["entity"] || data[:entity]
+      entity = nil
+      if entity_data.is_a?(Hash)
+        entity = EntityContext.new(
+          kind: entity_data["kind"] || entity_data[:kind],
+          key: entity_data["key"] || entity_data[:key],
+          attributes: entity_data["attributes"] || entity_data[:attributes] || {}
+        )
+      end
+
+      new(
+        identity: data["identity"] || data[:identity],
+        groups: data["groups"] || data[:groups] || [],
+        traits: data["traits"] || data[:traits] || {},
+        claims: data["claims"] || data[:claims] || {},
+        request: RequestContext.from_hash(data["request"] || data[:request]),
+        entity: entity
+      )
+    end
+
     # Check if context has an identity
     #
     # @return [Boolean]
@@ -77,6 +112,8 @@ module Toggly
         identity: @identity,
         groups: @groups,
         traits: @traits.merge(normalize_traits(new_traits)),
+        claims: @claims,
+        request: @request,
         entity: @entity
       )
     end
@@ -90,18 +127,79 @@ module Toggly
         identity: @identity,
         groups: @groups + new_groups.flatten.map(&:to_s),
         traits: @traits,
+        claims: @claims,
+        request: @request,
         entity: @entity
       )
     end
 
+    # Create a new context with the specified claims map.
+    #
+    # @param new_claims [Hash]
+    # @return [Context]
+    def with_claims(new_claims)
+      Context.new(
+        identity: @identity,
+        groups: @groups,
+        traits: @traits,
+        claims: new_claims,
+        request: @request,
+        entity: @entity
+      )
+    end
+
+    # Create a new context with the specified request fields.
+    #
+    # @param new_request [RequestContext, Hash, nil]
+    # @return [Context]
+    def with_request(new_request)
+      Context.new(
+        identity: @identity,
+        groups: @groups,
+        traits: @traits,
+        claims: @claims,
+        request: new_request,
+        entity: @entity
+      )
+    end
+
+    # Create a new context with the specified entity.
+    #
+    # @param new_entity [EntityContext, nil]
+    # @return [Context]
+    def with_entity(new_entity)
+      Context.new(
+        identity: @identity,
+        groups: @groups,
+        traits: @traits,
+        claims: @claims,
+        request: @request,
+        entity: new_entity
+      )
+    end
+
     # Convert to hash for serialization
     #
     # @return [Hash]
     def to_h
+      entity_hash =
+        if @entity.nil?
+          nil
+        else
+          {
+            kind: @entity.kind,
+            key: @entity.key,
+            attributes: @entity.attributes
+          }
+        end
+
       {
         identity: @identity,
         groups: @groups,
-        traits: @traits
+        traits: @traits,
+        claims: @claims,
+        request: @request&.to_h,
+        entity: entity_hash
       }
     end
 
@@ -114,7 +212,10 @@ module Toggly
 
       @identity == other.identity &&
         @groups.sort == other.groups.sort &&
-        @traits == other.traits
+        @traits == other.traits &&
+        @claims == other.claims &&
+        @request == other.request &&
+        @entity == other.entity
     end
     alias eql? ==
 
@@ -122,14 +223,14 @@ module Toggly
     #
     # @return [Integer]
     def hash
-      [@identity, @groups.sort, @traits].hash
+      [@identity, @groups.sort, @traits, @claims, @request, @entity].hash
     end
 
     # Generate cache key
     #
     # @return [String]
     def cache_key
-      "#{@identity}:#{@groups.sort.join(",")}:#{traits_cache_key}"
+      "#{@identity}:#{@groups.sort.join(",")}:#{traits_cache_key}:#{claims_cache_key}:#{request_cache_key}"
     end
 
     private
@@ -140,8 +241,33 @@ module Toggly
       traits.transform_keys(&:to_s)
     end
 
+    def normalize_claims(claims)
+      return {} unless claims.is_a?(Hash)
+
+      claims.each_with_object({}) do |(key, value), memo|
+        memo[key.to_s] = value.to_s
+      end
+    end
+
+    def coerce_request(request)
+      return nil if request.nil?
+      return request if request.is_a?(RequestContext)
+
+      RequestContext.from_hash(request)
+    end
+
     def traits_cache_key
       @traits.sort.map { |k, v| "#{k}=#{v}" }.join(",")
     end
+
+    def claims_cache_key
+      @claims.sort.map { |k, v| "#{k}=#{v}" }.join(",")
+    end
+
+    def request_cache_key
+      return "" unless @request
+
+      "#{@request.user_agent}|#{@request.accept_language}|#{@request.country}"
+    end
   end
 end

data/lib/toggly/evaluation_engine.rb

@@ -97,7 +97,7 @@ module Toggly
     def evaluate_filter_group(rules, requirement_type, context, feature_key, result)
       req = (requirement_type || "Any").to_s
       evaluations = rules.map do |rule|
-        rule_type = rule["type"] || rule[:type] || rule["name"] || rule[:name] || "always_on"
+        rule_type = rule["type"] || rule[:type] || rule["name"] || rule[:name] || "AlwaysOn"
         evaluator = @registry.get(rule_type)
         next false unless evaluator
 
@@ -115,12 +115,13 @@ module Toggly
 
     def sequential_rules(rules, definition, context, result)
       rules.each_with_index do |rule, index|
-        rule_type = rule["type"] || rule[:type] || rule["name"] || rule[:name] || "always_on"
+        rule_type = rule["type"] || rule[:type] || rule["name"] || rule[:name] || "AlwaysOn"
         evaluator = @registry.get(rule_type)
 
         unless evaluator
           log_warn("Unknown evaluator type: #{rule_type} for feature #{definition.feature_key}")
-          next
+          result&.reason = "unknown_filter"
+          return false
         end
 
         begin

data/lib/toggly/evaluators/always_off.rb

@@ -7,7 +7,11 @@ module Toggly
     # Used for features that should be disabled for everyone.
     class AlwaysOff < Base
       def self.type
-        "always_off"
+        "AlwaysOff"
+      end
+
+      def self.aliases
+        %w[always_off]
       end
 
       # @param rule [Hash] The rule configuration (ignored)

data/lib/toggly/evaluators/always_on.rb

@@ -7,7 +7,11 @@ module Toggly
     # Used for features that should be enabled for everyone.
     class AlwaysOn < Base
       def self.type
-        "always_on"
+        "AlwaysOn"
+      end
+
+      def self.aliases
+        %w[always_on]
       end
 
       # @param rule [Hash] The rule configuration (ignored)

data/lib/toggly/evaluators/base.rb

@@ -12,6 +12,13 @@ module Toggly
         raise NotImplementedError, "Subclass must implement .type"
       end
 
+      # Optional alternate registration names (e.g. Microsoft.* aliases).
+      #
+      # @return [Array<String>]
+      def self.aliases
+        []
+      end
+
       # Evaluate a rule against a context
       #
       # @param rule [Hash] The rule configuration
@@ -27,19 +34,30 @@ module Toggly
       # @param rule_type [String] The rule type
       # @return [Boolean]
       def handles?(rule_type)
-        rule_type.to_s.downcase == self.class.type.to_s.downcase
+        Registry.normalize_key(rule_type) == Registry.normalize_key(self.class.type)
       end
 
       protected
 
-      # Get a value from rule with fallback
+      # Get a value from rule with fallback (supports nested +parameters+).
       #
       # @param rule [Hash] The rule
       # @param key [String, Symbol] The key to lookup
       # @param default [Object] Default value
       # @return [Object]
       def rule_value(rule, key, default = nil)
-        rule[key.to_s] || rule[key.to_sym] || default
+        return default unless rule.is_a?(Hash)
+
+        params = rule["parameters"] || rule[:parameters]
+        candidates = [rule]
+        candidates << params if params.is_a?(Hash)
+
+        candidates.each do |source|
+          value = source[key.to_s] || source[key.to_sym] ||
+                  source.find { |k, _| k.to_s.casecmp?(key.to_s) }&.last
+          return value unless value.nil?
+        end
+        default
       end
 
       # Log evaluation result (if logger available)

data/lib/toggly/evaluators/browser_family.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator for BrowserFamily segment filters.
+    class BrowserFamily < Base
+      def self.type
+        "BrowserFamily"
+      end
+
+      def evaluate(rule, context, feature_key: nil)
+        percentage = SegmentHelpers.as_float(rule, "Percentage")
+        identity = context&.identity
+        return false unless StickyHash.segment_percentage_passes?(percentage, feature_key.to_s, identity)
+
+        values = SegmentHelpers.collect_indexed_values(rule, "BrowserFamily")
+        return false if values.empty?
+
+        ua = context&.request&.user_agent
+        parsed = UserAgentParser.parse(ua)
+        return false if parsed.nil? || parsed.browser_family == "Other"
+
+        values.any? { |value| SegmentHelpers.contains_ignore_case?(parsed.browser_family, value) }
+      end
+    end
+  end
+end

data/lib/toggly/evaluators/browser_language.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator for BrowserLanguage segment filters.
+    class BrowserLanguage < Base
+      def self.type
+        "BrowserLanguage"
+      end
+
+      def evaluate(rule, context, feature_key: nil)
+        percentage = SegmentHelpers.as_float(rule, "Percentage")
+        identity = context&.identity
+        return false unless StickyHash.segment_percentage_passes?(percentage, feature_key.to_s, identity)
+
+        values = SegmentHelpers.collect_indexed_values(rule, "BrowserLanguage")
+        return false if values.empty?
+
+        accept = context&.request&.accept_language
+        return false if accept.nil? || accept.empty?
+
+        values.any? { |value| SegmentHelpers.contains_ignore_case?(accept, value) }
+      end
+    end
+  end
+end

data/lib/toggly/evaluators/context_property.rb

@@ -5,7 +5,11 @@ module Toggly
     # Evaluator for ContextProperty entity filters. Fail closed.
     class ContextProperty < Base
       def self.type
-        "contextproperty"
+        "ContextProperty"
+      end
+
+      def self.aliases
+        %w[contextproperty]
       end
 
       def evaluate(rule, context, feature_key: nil)

data/lib/toggly/evaluators/contextual_targeting.rb

@@ -20,6 +20,10 @@ module Toggly
         "contextual"
       end
 
+      def self.aliases
+        %w[ContextualTargeting]
+      end
+
       # Evaluate contextual targeting rule
       #
       # @param rule [Hash] Rule with "conditions" array

data/lib/toggly/evaluators/country.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator for Country / CountryFamily segment filters.
+    class Country < Base
+      def self.type
+        "Country"
+      end
+
+      def self.aliases
+        %w[CountryFamily]
+      end
+
+      def evaluate(rule, context, feature_key: nil)
+        percentage = SegmentHelpers.as_float(rule, "Percentage")
+        identity = context&.identity
+        return false unless StickyHash.segment_percentage_passes?(percentage, feature_key.to_s, identity)
+
+        values = SegmentHelpers.collect_indexed_values(rule, "Country")
+        return false if values.empty?
+
+        country = context&.request&.country
+        return false if country.nil? || country.empty?
+
+        values.any? { |value| SegmentHelpers.equals_ignore_case?(value, country) }
+      end
+    end
+  end
+end

data/lib/toggly/evaluators/device_type.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator for DeviceType segment filters.
+    class DeviceType < Base
+      def self.type
+        "DeviceType"
+      end
+
+      def evaluate(rule, context, feature_key: nil)
+        percentage = SegmentHelpers.as_float(rule, "Percentage")
+        identity = context&.identity
+        return false unless StickyHash.segment_percentage_passes?(percentage, feature_key.to_s, identity)
+
+        values = SegmentHelpers.collect_indexed_values(rule, "DeviceType")
+        return false if values.empty?
+
+        ua = context&.request&.user_agent
+        parsed = UserAgentParser.parse(ua)
+        return false if parsed.nil? || parsed.device_family == "Other"
+
+        values.any? { |value| SegmentHelpers.contains_ignore_case?(parsed.device_family, value) }
+      end
+    end
+  end
+end

data/lib/toggly/evaluators/operating_system.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator for OS / OperatingSystem segment filters.
+    class OperatingSystem < Base
+      def self.type
+        "OperatingSystem"
+      end
+
+      def self.aliases
+        %w[OS]
+      end
+
+      def evaluate(rule, context, feature_key: nil)
+        percentage = SegmentHelpers.as_float(rule, "Percentage")
+        identity = context&.identity
+        return false unless StickyHash.segment_percentage_passes?(percentage, feature_key.to_s, identity)
+
+        values = SegmentHelpers.collect_indexed_values(rule, "OperatingSystem")
+        return false if values.empty?
+
+        ua = context&.request&.user_agent
+        parsed = UserAgentParser.parse(ua)
+        return false if parsed.nil? || parsed.os_family == "Other"
+
+        values.any? { |value| SegmentHelpers.contains_ignore_case?(parsed.os_family, value) }
+      end
+    end
+  end
+end

data/lib/toggly/evaluators/percentage.rb

@@ -4,68 +4,30 @@ module Toggly
   module Evaluators
     # Evaluator for percentage-based rollouts.
     #
-    # Uses FNV-1a hash for consistent bucketing based on
-    # feature key and user identity.
+    # Uses Definitions-aligned sticky SHA-256 hashing
+    # (+feature_key+ + "\n" + +identity+) for consistent buckets.
     class Percentage < Base
-      # FNV-1a hash constants (32-bit)
-      FNV_PRIME = 0x01000193
-      FNV_OFFSET_BASIS = 0x811c9dc5
-
       def self.type
-        "percentage"
+        "Percentage"
+      end
+
+      def self.aliases
+        %w[Microsoft.Percentage percentage]
       end
 
       # Evaluate percentage rollout
       #
-      # @param rule [Hash] Rule with "percentage" or "value" key (0-100)
+      # @param rule [Hash] Rule with Percentage / Value params (0-100)
       # @param context [Context] Evaluation context with identity
       # @param feature_key [String] The feature key
       # @return [Boolean] True if user falls within percentage
       def evaluate(rule, context, feature_key: nil)
-        percentage = rule_value(rule, "percentage") ||
-                     rule_value(rule, "value") ||
-                     0
-
-        percentage = percentage.to_f
-
-        # 0% always off, 100% always on
-        return false if percentage <= 0
+        percentage = SegmentHelpers.as_float(rule, "Value", "Percentage", "percentage", "value")
+        return false if percentage.nil? || percentage <= 0
         return true if percentage >= 100
-
-        # Need identity for percentage rollouts
         return false unless context&.identity?
 
-        # Calculate bucket using FNV-1a hash
-        bucket_key = "#{feature_key}:#{context.identity}"
-        bucket = calculate_bucket(bucket_key)
-
-        bucket < percentage
-      end
-
-      private
-
-      # Calculate bucket (0-100) using FNV-1a hash
-      #
-      # @param key [String] The key to hash
-      # @return [Float] Bucket value 0-100
-      def calculate_bucket(key)
-        hash = fnv1a_hash(key)
-        (hash % 10_000) / 100.0
-      end
-
-      # FNV-1a hash implementation
-      #
-      # @param data [String] Data to hash
-      # @return [Integer] 32-bit hash value
-      def fnv1a_hash(data)
-        hash = FNV_OFFSET_BASIS
-
-        data.each_byte do |byte|
-          hash ^= byte
-          hash = (hash * FNV_PRIME) & 0xFFFFFFFF
-        end
-
-        hash
+        StickyHash.compute_percentile(context.identity, feature_key.to_s) < percentage
       end
     end
   end