toggly 0.2.1 → 0.5.0

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