toggly 0.2.0 → 0.3.0

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.0"
+  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)