toggly 0.2.1 → 0.5.0

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/definition_cache.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Shared definition-refresh cache helpers (hit/miss classification).
+  module DefinitionCache
+    module_function
+
+    # Normalize an ETag/revision for comparison (strip weak prefix + quotes).
+    #
+    # @param etag [String, nil]
+    # @return [String, nil]
+    def normalize_etag(etag)
+      return nil if etag.nil?
+
+      trimmed = etag.to_s.strip
+      return nil if trimmed.empty?
+
+      trimmed = trimmed[2..].to_s.strip if trimmed.length >= 2 && %w[W w].include?(trimmed[0]) && trimmed[1] == "/"
+      return trimmed[1...-1] if trimmed.length >= 2 && trimmed.start_with?('"') && trimmed.end_with?('"')
+
+      trimmed
+    end
+
+    # @param left [String, nil]
+    # @param right [String, nil]
+    # @return [Boolean]
+    def etags_match?(left, right)
+      a = normalize_etag(left)
+      b = normalize_etag(right)
+      !a.nil? && !b.nil? && a == b
+    end
+
+    # @param left [String, nil]
+    # @param right [String, nil]
+    # @return [Boolean]
+    def last_modified_match?(left, right)
+      a = left&.to_s&.strip
+      b = right&.to_s&.strip
+      !a.nil? && !b.nil? && !a.empty? && a == b
+    end
+
+    # Match Go isCachedRevision: currentTS > 0 && incomingTS <= currentTS → hit.
+    #
+    # @param current_ts [Integer, nil]
+    # @param incoming_ts [Integer, nil]
+    # @return [Boolean]
+    def cached_signed_timestamp?(current_ts, incoming_ts)
+      return false if incoming_ts.nil?
+
+      current = current_ts.to_i
+      incoming = incoming_ts.to_i
+      current.positive? && incoming <= current
+    end
+
+    # Classify an HTTP definitions response for cache telemetry.
+    #
+    # @param status_code [Integer]
+    # @param existing_etag [String, nil]
+    # @param response_etag [String, nil]
+    # @param existing_last_modified [String, nil]
+    # @param response_last_modified [String, nil]
+    # @return [Symbol] :not_modified, :same_revision, :new_content, or :error_status
+    def classify_http(
+      status_code,
+      existing_etag,
+      response_etag,
+      existing_last_modified: nil,
+      response_last_modified: nil
+    )
+      return :not_modified if status_code == 304
+      return :error_status if status_code != 200
+      return :same_revision if etags_match?(existing_etag, response_etag)
+      return :same_revision if last_modified_match?(existing_last_modified, response_last_modified)
+
+      :new_content
+    end
+  end
+end

data/lib/toggly/definitions_provider.rb

@@ -14,6 +14,9 @@ end
 module Toggly
   # Provider for fetching feature definitions from Toggly API.
   class DefinitionsProvider
+    # Result of one HTTP definitions fetch with cache telemetry outcome.
+    FetchResult = Struct.new(:definitions, :cache_outcome, keyword_init: true)
+
     # Fallback HTTP refresh interval when WebSocket is connected (20 minutes)
     FALLBACK_REFRESH_INTERVAL = 20 * 60
 
@@ -32,6 +35,7 @@ module Toggly
       @on_definitions_updated = on_definitions_updated
       @etag = nil
       @last_modified = nil
+      @last_ts = 0
 
       # WebSocket state
       @ws = nil
@@ -44,11 +48,11 @@ module Toggly
     # Fetch definitions from the API
     #
     # @param force [Boolean] Force fetch even if cached
-    # @return [Hash, nil] Hash of definitions, or nil if not modified
+    # @return [FetchResult] definitions (Hash or nil) plus :hit / :miss outcome
     # @raise [NetworkError] On network failures
     # @raise [DefinitionsError] On API errors
     def fetch(force: false)
-      return nil if @config.offline_mode?
+      return FetchResult.new(definitions: nil, cache_outcome: :hit) if @config.offline_mode?
 
       uri = URI.parse(@config.definitions_endpoint)
       http = build_http(uri)
@@ -60,6 +64,8 @@ module Toggly
       raise NetworkError, "Request timeout: #{e.message}"
     rescue SocketError, Errno::ECONNREFUSED => e
       raise NetworkError, "Connection failed: #{e.message}"
+    rescue NetworkError, DefinitionsError
+      raise
     rescue StandardError => e
       raise NetworkError, "Request failed: #{e.message}"
     end
@@ -68,6 +74,7 @@ module Toggly
     def reset_cache
       @etag = nil
       @last_modified = nil
+      @last_ts = 0
     end
 
     # Check whether the periodic refresh should be skipped because the
@@ -166,32 +173,81 @@ module Toggly
     end
 
     def handle_response(response)
-      case response.code.to_i
-      when 200
-        parse_definitions(response)
-      when 304
-        # Not modified
+      status = response.code.to_i
+      response_etag = response["ETag"]
+      response_lm = response["Last-Modified"]
+      kind = DefinitionCache.classify_http(
+        status,
+        @etag,
+        response_etag,
+        existing_last_modified: @last_modified,
+        response_last_modified: response_lm
+      )
+
+      case kind
+      when :not_modified
         log_debug("Definitions not modified")
-        nil
+        FetchResult.new(definitions: nil, cache_outcome: :hit)
+      when :same_revision
+        log_debug("Definitions revision matches existing (ETag or Last-Modified)")
+        store_revision_headers(response_etag, response_lm)
+        FetchResult.new(definitions: nil, cache_outcome: :hit)
+      when :new_content
+        handle_new_content(response, response_etag, response_lm)
+      when :error_status
+        handle_error_status(status, response)
+      end
+    end
+
+    def handle_new_content(response, response_etag, response_lm)
+      data = JSON.parse(response.body)
+      signed_ts = extract_signed_timestamp(data)
+      if DefinitionCache.cached_signed_timestamp?(@last_ts, signed_ts)
+        log_debug("Definitions signed timestamp is not newer than cached revision")
+        store_revision_headers(response_etag, response_lm)
+        return FetchResult.new(definitions: nil, cache_outcome: :hit)
+      end
+
+      definitions = parse_features(data)
+      store_revision_headers(response_etag, response_lm)
+      @last_ts = signed_ts if signed_ts&.positive?
+      FetchResult.new(definitions: definitions, cache_outcome: :miss)
+    rescue JSON::ParserError => e
+      raise DefinitionsError, "Failed to parse definitions: #{e.message}"
+    end
+
+    def handle_error_status(status, response)
+      case status
       when 401, 403
-        raise DefinitionsError, "Authentication failed: #{response.code}"
+        raise DefinitionsError, "Authentication failed: #{status}"
       when 404
         raise DefinitionsError, "Definitions not found (check app_key and environment)"
       else
         raise NetworkError.new(
-          "API error: #{response.code}",
-          status_code: response.code.to_i,
+          "API error: #{status}",
+          status_code: status,
           response_body: response.body
         )
       end
     end
 
-    def parse_definitions(response)
-      # Cache headers for conditional requests
-      @etag = response["ETag"]
-      @last_modified = response["Last-Modified"]
+    def store_revision_headers(etag, last_modified)
+      @etag = etag if etag && !etag.empty?
+      @last_modified = last_modified if last_modified && !last_modified.empty?
+    end
 
-      data = JSON.parse(response.body)
+    def extract_signed_timestamp(data)
+      return nil unless data.is_a?(Hash)
+
+      raw = data["timestamp"]
+      return nil if raw.nil?
+
+      Integer(raw)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def parse_features(data)
       features = if data.is_a?(Hash)
                    data["defs"] || data["features"] || data
                  else
@@ -209,8 +265,6 @@ module Toggly
       else
         raise DefinitionsError, "Invalid definitions format"
       end
-    rescue JSON::ParserError => e
-      raise DefinitionsError, "Failed to parse definitions: #{e.message}"
     end
 
     def build_websocket_url

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