toggly 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 661719eeb6fb2dec747b0f3bfd1dfa08349702573d583f72919abb6c5b6ae8d0
-  data.tar.gz: f1fdf90d3fa48390637f5ea000c21a6002f6764623ed562b822569f3e0e10862
+  metadata.gz: 7b199467e0cb56245072bf1b0bda7b00ddf7931be0c87e691dac159287f1304e
+  data.tar.gz: 184d195d8caf6321358d2bda8894f8134d1bd2d5ddc3eca6dfd92c7c7c19595b
 SHA512:
-  metadata.gz: 4e6045eb73a91c81ccb3d9e7f3b4096958453f825025b18be81707beb6d96a6ca8f636ab1ee2e6b2852ccca5c7461d93009906de1967bf3a04a44e08425ce70d
-  data.tar.gz: c19d57ca41c649c359c29a0c4d6b5c8377d8cdcb03c4fdd1ff8020559d5d9788929aa9ee88e8281226e5e3175c1d8bb5647184c8d3d3c307a21ad6306c7f7546
+  metadata.gz: ddfa9d5bcbf04311a427752c3dba07edb52b841e61f8630d6b9beca6d34d34d1c53b3107f7ca1c9a07f73a8d796278ef2296cd0b723d1ed83be2504277e4449b
+  data.tar.gz: 76bf82b4e3e23cdfea1beb0edd735a2be3ae8ce38982c7bfc75dcc00093160666b7372815ea462480590edf7c72dd0ec0b71a2bc11661b0510b8d85c39425c88

data/CHANGELOG.md

@@ -5,6 +5,29 @@ 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

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

data/lib/toggly/evaluators/segment_helpers.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Shared helpers for Definitions-style segment / claims filters.
+    module SegmentHelpers
+      module_function
+
+      # @param rule [Hash]
+      # @return [Hash]
+      def parameters(rule)
+        return {} unless rule.is_a?(Hash)
+
+        params = rule["parameters"] || rule[:parameters]
+        params.is_a?(Hash) ? params : rule
+      end
+
+      # @param rule [Hash]
+      # @param keys [Array<String>]
+      # @return [Float, nil]
+      def as_float(rule, *keys)
+        params = parameters(rule)
+        keys.each do |key|
+          value = lookup(params, key)
+          next if value.nil?
+          next if [true, false].include?(value)
+
+          begin
+            return Float(value)
+          rescue ArgumentError, TypeError
+            return nil
+          end
+        end
+        nil
+      end
+
+      # @param rule [Hash]
+      # @param key [String]
+      # @return [String, nil]
+      def as_string(rule, key)
+        value = lookup(parameters(rule), key)
+        return nil if value.nil?
+
+        text = value.to_s
+        text.empty? ? nil : text
+      end
+
+      # Collect indexed RavenDB / legacy colon-prefixed parameter values.
+      #
+      # @param rule [Hash]
+      # @param prefixes [Array<String>]
+      # @return [Array<String>]
+      def collect_indexed_values(rule, *prefixes)
+        params = parameters(rule)
+        out = []
+        params.each do |key, value|
+          next if value.nil?
+
+          key_s = key.to_s
+          prefixes.each do |prefix|
+            next unless key_s.start_with?("#{prefix}:")
+
+            text = value.to_s
+            out << text unless text.empty?
+            break
+          end
+        end
+        out
+      end
+
+      # @param haystack [String, nil]
+      # @param needle [String, nil]
+      # @return [Boolean]
+      def contains_ignore_case?(haystack, needle)
+        return false if haystack.nil? || needle.nil?
+
+        haystack.downcase.include?(needle.downcase)
+      end
+
+      # @param left [String, nil]
+      # @param right [String, nil]
+      # @return [Boolean]
+      def equals_ignore_case?(left, right)
+        return false if left.nil? || right.nil?
+
+        left.casecmp?(right)
+      end
+
+      def lookup(params, key)
+        return nil unless params.is_a?(Hash)
+
+        params[key] || params[key.to_s] || params[key.to_sym] ||
+          params.find { |k, _| k.to_s.casecmp?(key.to_s) }&.last
+      end
+      module_function :lookup
+    end
+  end
+end

data/lib/toggly/evaluators/targeting.rb

@@ -7,45 +7,92 @@ module Toggly
     # Supports targeting by:
     # - Specific user identities
     # - Group membership
+    # - Definitions Audience.* indexed params and default rollout
     class Targeting < Base
       def self.type
-        "targeting"
+        "Targeting"
+      end
+
+      def self.aliases
+        %w[Microsoft.Targeting targeting]
       end
 
       # Evaluate targeting rule
       #
-      # @param rule [Hash] Rule with "users" and/or "groups" arrays
+      # @param rule [Hash] Rule with users/groups or Audience.* params
       # @param context [Context] Evaluation context
       # @param feature_key [String] The feature key
       # @return [Boolean, nil] True if matched, false if excluded, nil to continue
       def evaluate(rule, context, feature_key: nil)
         return nil unless context
 
-        # Check user targeting
-        users = Array(rule_value(rule, "users"))
+        users = collect_users(rule)
         excluded_users = Array(rule_value(rule, "excludedUsers") || rule_value(rule, "excluded_users"))
 
         if context.identity?
-          # Check exclusion first
           return false if excluded_users.any? { |u| u.to_s == context.identity }
-
-          # Check inclusion
-          return true if users.any? { |u| u.to_s == context.identity }
+          return true if users.include?(context.identity)
         end
 
-        # Check group targeting
-        groups = Array(rule_value(rule, "groups"))
+        groups = collect_groups(rule)
         excluded_groups = Array(rule_value(rule, "excludedGroups") || rule_value(rule, "excluded_groups"))
 
-        # Check group exclusion
         return false if excluded_groups.any? { |g| context.in_group?(g) }
-
-        # Check group inclusion
         return true if groups.any? { |g| context.in_group?(g) }
 
-        # No match, continue evaluation
+        default_percentage = SegmentHelpers.as_float(
+          rule,
+          "Audience.DefaultRolloutPercentage",
+          "DefaultRolloutPercentage",
+          "defaultRolloutPercentage",
+          "default_percentage",
+          "Percentage"
+        )
+        return StickyHash.compute_percentile(context.identity, feature_key.to_s) < default_percentage if default_percentage&.positive? && context.identity?
+
+        # No match — continue evaluation for legacy sequential rules
         nil
       end
+
+      private
+
+      def collect_users(rule)
+        users = []
+        append_list_values(users, rule_value(rule, "users") || rule_value(rule, "Users"))
+        SegmentHelpers.parameters(rule).each do |key, value|
+          next unless key.to_s.start_with?("Audience.Users:") && value
+
+          users << value.to_s
+        end
+        users.uniq
+      end
+
+      def collect_groups(rule)
+        groups = []
+        append_list_values(groups, rule_value(rule, "groups") || rule_value(rule, "Groups"))
+        SegmentHelpers.parameters(rule).each do |key, value|
+          next unless key.to_s.start_with?("Audience.Groups:") && value
+
+          groups << value.to_s
+        end
+        groups.uniq
+      end
+
+      def append_list_values(memo, raw)
+        case raw
+        when Array
+          raw.each { |item| memo << item.to_s }
+        when String
+          raw.split(",").each do |item|
+            trimmed = item.strip
+            memo << trimmed unless trimmed.empty?
+          end
+        when nil
+          nil
+        else
+          memo << raw.to_s
+        end
+      end
     end
   end
 end

data/lib/toggly/evaluators/time_window.rb

@@ -7,12 +7,16 @@ module Toggly
     # Enables features within a specific time range.
     class TimeWindow < Base
       def self.type
-        "time_window"
+        "TimeWindow"
+      end
+
+      def self.aliases
+        %w[Microsoft.TimeWindow time_window]
       end
 
       # Evaluate time window rule
       #
-      # @param rule [Hash] Rule with "startTime"/"start_time" and/or "endTime"/"end_time"
+      # @param rule [Hash] Rule with Start/End or startTime/endTime
       # @param context [Context] Evaluation context (ignored)
       # @param feature_key [String] The feature key
       # @return [Boolean] True if current time is within window
@@ -20,19 +24,20 @@ module Toggly
         now = Time.now.utc
 
         start_time = parse_time(
-          rule_value(rule, "startTime") || rule_value(rule, "start_time")
+          rule_value(rule, "Start") ||
+          rule_value(rule, "start") ||
+          rule_value(rule, "startTime") ||
+          rule_value(rule, "start_time")
         )
         end_time = parse_time(
-          rule_value(rule, "endTime") || rule_value(rule, "end_time")
+          rule_value(rule, "End") ||
+          rule_value(rule, "end") ||
+          rule_value(rule, "endTime") ||
+          rule_value(rule, "end_time")
         )
 
-        # No time constraints means always valid
         return true if start_time.nil? && end_time.nil?
-
-        # Check start time
         return false if start_time && now < start_time
-
-        # Check end time
         return false if end_time && now > end_time
 
         true

data/lib/toggly/evaluators/user_claims.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator for UserClaims filters (Claim + Value params).
+    class UserClaims < Base
+      def self.type
+        "UserClaims"
+      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)
+
+        claim_type = SegmentHelpers.as_string(rule, "Claim")
+        claim_value = SegmentHelpers.as_string(rule, "Value")
+        return false if claim_type.nil? || claim_value.nil? || context.nil?
+
+        claims = context.claims
+        return false if claims.nil? || !claims.key?(claim_type)
+
+        claim_value == claims[claim_type]
+      end
+    end
+  end
+end

data/lib/toggly/feature_definition.rb

@@ -38,7 +38,7 @@ module Toggly
     # Feature types
     TYPES = %w[Release Experiment Ops Permission].freeze
 
-    # rubocop:disable Metrics/ParameterLists
+    # rubocop:disable-next Metrics/ParameterLists
     def initialize(
       feature_key:,
       feature_type: "Release",
@@ -64,7 +64,6 @@ module Toggly
       @context_kind = context_kind
       @context_requirement_type = context_requirement_type
     end
-    # rubocop:enable Metrics/ParameterLists
 
     # Create from a hash (e.g., from JSON)
     #

data/lib/toggly/http_request_mapper.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Maps common HTTP headers into RequestContext fields.
+  #
+  # Does not invent identity, groups, or claims — merge those separately.
+  class HttpRequestMapper
+    COUNTRY_HEADERS = %w[
+      cf-ipcountry
+      x-vercel-ip-country
+      cloudfront-viewer-country
+    ].freeze
+
+    class << self
+      # Build RequestContext from a header bag (case-insensitive keys).
+      #
+      # @param headers [Hash, nil]
+      # @return [RequestContext]
+      def from_http_headers(headers)
+        return RequestContext.new if headers.nil? || headers.empty?
+
+        RequestContext.new(
+          user_agent: header(headers, "user-agent"),
+          accept_language: header(headers, "accept-language"),
+          country: first_present(headers, *COUNTRY_HEADERS)
+        )
+      end
+
+      # Merge HTTP-mapped request fields over an existing evaluation context.
+      #
+      # @param headers [Hash, nil]
+      # @param base [Context, nil]
+      # @return [Context]
+      def merge_into(headers, base)
+        request = from_http_headers(headers)
+        return Context.new(request: request) if base.nil?
+
+        base.with_request(request)
+      end
+
+      private
+
+      def first_present(headers, *names)
+        names.each do |name|
+          value = header(headers, name)
+          return value if value
+        end
+        nil
+      end
+
+      def header(headers, name)
+        lower = name.downcase
+        headers.each do |key, value|
+          next unless key && key.to_s.downcase == lower
+          next if value.nil?
+
+          text = value.to_s
+          return text unless text.empty?
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/toggly/registry.rb

@@ -12,13 +12,26 @@ module Toggly
       register_defaults
     end
 
-    # Register an evaluator
+    # Normalize filter / evaluator names for lookup.
+    # Strips non-alphanumeric characters so AlwaysOn and always_on match.
+    #
+    # @param type [String, Symbol]
+    # @return [String]
+    def self.normalize_key(type)
+      type.to_s.downcase.gsub(/[^a-z0-9]/, "")
+    end
+
+    # Register an evaluator (and optional extra aliases).
     #
     # @param evaluator [Evaluators::Base] The evaluator instance
+    # @param extra_aliases [Array<String>] Additional names
     # @return [self]
-    def register(evaluator)
+    def register(evaluator, *extra_aliases)
+      names = [evaluator.class.type, *Array(evaluator.class.aliases), *extra_aliases]
       @mutex.synchronize do
-        @evaluators[evaluator.class.type.to_s.downcase] = evaluator
+        names.compact.each do |name|
+          @evaluators[self.class.normalize_key(name)] = evaluator
+        end
       end
       self
     end
@@ -29,7 +42,7 @@ module Toggly
     # @return [Evaluators::Base, nil]
     def get(type)
       @mutex.synchronize do
-        @evaluators[type.to_s.downcase]
+        @evaluators[self.class.normalize_key(type)]
       end
     end
 
@@ -39,7 +52,7 @@ module Toggly
     # @return [Boolean]
     def registered?(type)
       @mutex.synchronize do
-        @evaluators.key?(type.to_s.downcase)
+        @evaluators.key?(self.class.normalize_key(type))
       end
     end
 
@@ -58,7 +71,7 @@ module Toggly
     # @return [Evaluators::Base, nil] The removed evaluator
     def unregister(type)
       @mutex.synchronize do
-        @evaluators.delete(type.to_s.downcase)
+        @evaluators.delete(self.class.normalize_key(type))
       end
     end
 
@@ -82,6 +95,12 @@ module Toggly
       register(Evaluators::TimeWindow.new)
       register(Evaluators::ContextualTargeting.new)
       register(Evaluators::ContextProperty.new)
+      register(Evaluators::BrowserFamily.new)
+      register(Evaluators::BrowserLanguage.new)
+      register(Evaluators::Country.new)
+      register(Evaluators::DeviceType.new)
+      register(Evaluators::OperatingSystem.new)
+      register(Evaluators::UserClaims.new)
     end
   end
 end

data/lib/toggly/request_context.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Toggly
+  # HTTP request fields used by segment identity filters.
+  class RequestContext
+    # @return [String, nil]
+    attr_reader :user_agent, :accept_language, :country
+
+    def initialize(user_agent: nil, accept_language: nil, country: nil)
+      @user_agent = blank_to_nil(user_agent)
+      @accept_language = blank_to_nil(accept_language)
+      @country = blank_to_nil(country)
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        userAgent: @user_agent,
+        acceptLanguage: @accept_language,
+        country: @country
+      }
+    end
+
+    # Create from a hash accepting camelCase or snake_case keys.
+    #
+    # @param data [Hash, nil]
+    # @return [RequestContext, nil]
+    def self.from_hash(data)
+      return nil unless data.is_a?(Hash)
+
+      new(
+        user_agent: first_value(data, "userAgent", "user_agent"),
+        accept_language: first_value(data, "acceptLanguage", "accept_language"),
+        country: first_value(data, "country")
+      )
+    end
+
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(RequestContext)
+
+      @user_agent == other.user_agent &&
+        @accept_language == other.accept_language &&
+        @country == other.country
+    end
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      [@user_agent, @accept_language, @country].hash
+    end
+
+    def self.first_value(data, *keys)
+      keys.each do |key|
+        next unless data.key?(key) || data.key?(key.to_sym)
+
+        value = data[key] || data[key.to_sym]
+        next if value.nil?
+
+        text = value.to_s
+        return text unless text.empty?
+      end
+      nil
+    end
+    private_class_method :first_value
+
+    private
+
+    def blank_to_nil(value)
+      return nil if value.nil?
+
+      text = value.to_s
+      text.empty? ? nil : text
+    end
+  end
+end

data/lib/toggly/sticky_hash.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+
+module Toggly
+  # Sticky percentage bucketing aligned with Definitions / toggly-eval.
+  module StickyHash
+    module_function
+
+    # Sticky bucket in [0, 100) matching Definitions / toggly-eval SHA-256.
+    #
+    # Hash input is +feature_key+ + "\n" + +user_id+; little-endian uint32 from
+    # the first 4 digest bytes, then +(value / 0xFFFFFFFF) * 100+.
+    #
+    # @param user_id [String]
+    # @param feature_key [String]
+    # @return [Float]
+    def compute_percentile(user_id, feature_key)
+      digest = Digest::SHA256.digest("#{feature_key}\n#{user_id}")
+      value = digest.byteslice(0, 4).unpack1("V")
+      (value.to_f / 0xFFFFFFFF) * 100.0
+    end
+
+    # Percentage gate for segment filters; missing or ≤0 fails closed.
+    #
+    # @param percentage [Numeric, nil]
+    # @param feature_key [String]
+    # @param identity [String, nil]
+    # @return [Boolean]
+    def segment_percentage_passes?(percentage, feature_key, identity)
+      return false if percentage.nil? || percentage <= 0
+      return true if percentage >= 100
+      return compute_percentile(identity, feature_key) < percentage if identity && !identity.empty?
+
+      SecureRandom.random_number * 100 < percentage
+    end
+  end
+end

data/lib/toggly/user_agent_parser.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Best-effort User-Agent parse result for segment filters.
+  class ParsedUserAgent
+    # @return [String]
+    attr_reader :browser_family, :os_family, :device_family
+
+    def initialize(browser_family:, os_family:, device_family:)
+      @browser_family = browser_family
+      @os_family = os_family
+      @device_family = device_family
+    end
+  end
+
+  # Best-effort UA parsing (parity with toggly-eval / Java / Python).
+  module UserAgentParser
+    module_function
+
+    # @param user_agent [String, nil]
+    # @return [ParsedUserAgent, nil]
+    def parse(user_agent)
+      return nil if user_agent.nil? || user_agent.empty?
+
+      ParsedUserAgent.new(
+        browser_family: detect_browser(user_agent),
+        os_family: detect_os(user_agent),
+        device_family: detect_device(user_agent)
+      )
+    end
+
+    def detect_browser(user_agent)
+      return "Edge" if user_agent.include?("Edg/") || user_agent.include?("EdgiOS/")
+      return "Opera" if user_agent.include?("OPR/") || user_agent.include?("Opera")
+      return "Chrome" if user_agent.include?("Chrome/") || user_agent.include?("CriOS/")
+      return "Firefox" if user_agent.include?("Firefox/") || user_agent.include?("FxiOS/")
+      if user_agent.include?("Safari/") && user_agent.include?("Version/") &&
+         !user_agent.include?("Chrome") && !user_agent.include?("Chromium")
+        return "Safari"
+      end
+
+      "Other"
+    end
+    module_function :detect_browser
+
+    def detect_os(user_agent)
+      return "Android" if user_agent.include?("Android")
+      if user_agent.include?("iPhone") || user_agent.include?("iPad") || user_agent.include?("iPod") ||
+         user_agent.include?("CPU iPhone OS") || user_agent.include?("CPU OS")
+        return "iOS"
+      end
+      return "Mac OS" if user_agent.include?("Mac OS X") || user_agent.include?("Macintosh")
+      return "Windows" if user_agent.include?("Windows")
+      return "Linux" if user_agent.include?("Linux")
+
+      "Other"
+    end
+    module_function :detect_os
+
+    def detect_device(user_agent)
+      return "iPhone" if user_agent.include?("iPhone")
+      return "iPad" if user_agent.include?("iPad")
+      return "iPod" if user_agent.include?("iPod")
+
+      "Other"
+    end
+    module_function :detect_device
+  end
+end

data/lib/toggly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Toggly
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/toggly.rb

@@ -2,10 +2,15 @@
 
 require_relative "toggly/version"
 require_relative "toggly/config"
+require_relative "toggly/request_context"
+require_relative "toggly/http_request_mapper"
+require_relative "toggly/sticky_hash"
+require_relative "toggly/user_agent_parser"
 require_relative "toggly/context"
 require_relative "toggly/errors"
 require_relative "toggly/feature_definition"
 require_relative "toggly/evaluators/base"
+require_relative "toggly/evaluators/segment_helpers"
 require_relative "toggly/evaluators/always_on"
 require_relative "toggly/evaluators/always_off"
 require_relative "toggly/evaluators/percentage"
@@ -13,6 +18,12 @@ require_relative "toggly/evaluators/targeting"
 require_relative "toggly/evaluators/time_window"
 require_relative "toggly/evaluators/contextual_targeting"
 require_relative "toggly/evaluators/context_property"
+require_relative "toggly/evaluators/browser_family"
+require_relative "toggly/evaluators/browser_language"
+require_relative "toggly/evaluators/country"
+require_relative "toggly/evaluators/device_type"
+require_relative "toggly/evaluators/operating_system"
+require_relative "toggly/evaluators/user_claims"
 require_relative "toggly/entity_context"
 require_relative "toggly/registry"
 require_relative "toggly/evaluation_engine"
@@ -38,7 +49,9 @@ require_relative "toggly/client"
 #   context = Toggly::Context.new(
 #     identity: "user-123",
 #     groups: ["beta-testers"],
-#     traits: { country: "US" }
+#     claims: { "role" => "admin" },
+#     request: Toggly::RequestContext.new(country: "US"),
+#     traits: { plan: "enterprise" }
 #   )
 #
 #   if client.enabled?("premium-feature", context: context)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toggly
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Ops.ai
@@ -32,16 +32,27 @@ files:
 - lib/toggly/evaluators/always_off.rb
 - lib/toggly/evaluators/always_on.rb
 - lib/toggly/evaluators/base.rb
+- lib/toggly/evaluators/browser_family.rb
+- lib/toggly/evaluators/browser_language.rb
 - lib/toggly/evaluators/context_property.rb
 - lib/toggly/evaluators/contextual_targeting.rb
+- lib/toggly/evaluators/country.rb
+- lib/toggly/evaluators/device_type.rb
+- lib/toggly/evaluators/operating_system.rb
 - lib/toggly/evaluators/percentage.rb
+- lib/toggly/evaluators/segment_helpers.rb
 - lib/toggly/evaluators/targeting.rb
 - lib/toggly/evaluators/time_window.rb
+- lib/toggly/evaluators/user_claims.rb
 - lib/toggly/feature_definition.rb
+- lib/toggly/http_request_mapper.rb
 - lib/toggly/registry.rb
+- lib/toggly/request_context.rb
 - lib/toggly/snapshot_providers/base.rb
 - lib/toggly/snapshot_providers/file.rb
 - lib/toggly/snapshot_providers/memory.rb
+- lib/toggly/sticky_hash.rb
+- lib/toggly/user_agent_parser.rb
 - lib/toggly/version.rb
 homepage: https://toggly.io
 licenses: