toggly 0.6.0 → 1.1.0

data/lib/toggly/variant_allocator.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Toggly
+  # Catalog-local, MF-parity variant allocator.
+  #
+  # Assigns a feature variant purely from a {FeatureDefinition}'s
+  # `variants` / `allocation` and a targeting context (`identity` + `groups`),
+  # bit-for-bit matching `Microsoft.FeatureManagement` 4.7.0's
+  # `FeatureManager#GetVariantAsync`. Verified against the shared
+  # `variant-allocator-corpus/cases.json` gold corpus.
+  #
+  # This replaces the `evaluated-variants-signed` dual-rail: there is no
+  # network call here — the caller supplies the already filter-evaluated
+  # `enabled` boolean (the same value `Client#enabled?` would return for
+  # this feature/context) and this module does the rest locally.
+  module VariantAllocator
+    module_function
+
+    # Assignment reasons (mirrors MF `AssignmentReason`).
+    REASON_NONE = "None"
+    REASON_USER = "User"
+    REASON_GROUP = "Group"
+    REASON_PERCENTILE = "Percentile"
+    REASON_DEFAULT_WHEN_ENABLED = "DefaultWhenEnabled"
+    REASON_DEFAULT_WHEN_DISABLED = "DefaultWhenDisabled"
+
+    # Result of a variant assignment.
+    #
+    # @!attribute variant_name [String, nil] Assigned variant name, or nil if unassigned
+    # @!attribute configuration_value [Object, nil] The assigned variant's configuration payload
+    # @!attribute enabled [Boolean] Effective enabled flag after StatusOverride is applied
+    # @!attribute reason [String] One of the REASON_* constants above
+    Assignment = Struct.new(:variant_name, :configuration_value, :enabled, :reason, keyword_init: true)
+
+    # Assign a variant for a feature + targeting context.
+    #
+    # @param definition [FeatureDefinition] Feature definition (variants + allocation)
+    # @param enabled [Boolean] The filter-evaluated enabled state for this context
+    #   (i.e. what `EvaluationEngine#evaluate` returns for this definition/context)
+    # @param identity [String, nil] Targeting user id
+    # @param groups [Array<String>] Targeting groups
+    # @param ignore_case [Boolean] MF `TargetingEvaluationOptions.IgnoreCase` parity knob.
+    #   Defaults to `false`, matching Microsoft.FeatureManagement's default.
+    # @return [Assignment]
+    def assign(definition, enabled:, identity: nil, groups: [], ignore_case: false)
+      variants = definition&.variants || []
+      allocation = definition&.allocation
+
+      return build_assignment(nil, variants, enabled, REASON_NONE) if variants.empty?
+
+      unless enabled
+        variant_name = allocation&.default_when_disabled
+        return build_assignment(variant_name, variants, enabled, REASON_DEFAULT_WHEN_DISABLED)
+      end
+
+      variant_name, reason = resolve_enabled_allocation(
+        allocation, identity, groups, ignore_case, definition.feature_key
+      )
+      build_assignment(variant_name, variants, enabled, reason)
+    end
+
+    def resolve_enabled_allocation(allocation, identity, groups, ignore_case, feature_key)
+      return [nil, REASON_DEFAULT_WHEN_ENABLED] unless allocation
+
+      user_variant = match_user(allocation.user, identity, ignore_case)
+      return [user_variant, REASON_USER] if user_variant
+
+      group_variant = match_group(allocation.group, groups, ignore_case)
+      return [group_variant, REASON_GROUP] if group_variant
+
+      percentile_variant = match_percentile(allocation.percentile, allocation.seed, identity, feature_key, ignore_case)
+      return [percentile_variant, REASON_PERCENTILE] if percentile_variant
+
+      [allocation.default_when_enabled, REASON_DEFAULT_WHEN_ENABLED]
+    end
+
+    def match_user(entries, identity, ignore_case)
+      return nil if identity.nil? || identity.to_s.empty?
+
+      Array(entries).each do |entry|
+        users = Array(entry[:users])
+        matched = if ignore_case
+                    users.any? { |u| u.to_s.casecmp?(identity.to_s) }
+                  else
+                    users.include?(identity.to_s)
+                  end
+        return entry[:variant] if matched
+      end
+      nil
+    end
+
+    def match_group(entries, groups, ignore_case)
+      context_groups = Array(groups).map(&:to_s)
+      return nil if context_groups.empty?
+
+      Array(entries).each do |entry|
+        entry_groups = Array(entry[:groups]).map(&:to_s)
+        matched = if ignore_case
+                    entry_groups.any? { |eg| context_groups.any? { |cg| cg.casecmp?(eg) } }
+                  else
+                    entry_groups.intersect?(context_groups)
+                  end
+        return entry[:variant] if matched
+      end
+      nil
+    end
+
+    def match_percentile(entries, seed, identity, feature_key, ignore_case)
+      list = Array(entries)
+      return nil if list.empty?
+
+      pct = compute_percentile(identity, seed, feature_key, ignore_case)
+      list.each do |entry|
+        from = entry[:from].to_f
+        to = entry[:to].to_f
+        matched = to >= 100.0 ? pct >= from : (pct >= from && pct < to)
+        return entry[:variant] if matched
+      end
+      nil
+    end
+
+    # MF-parity percentile hash.
+    #
+    # `contextId = "{userId}\n{hint}"`, `hint = seed` (if non-nil) else
+    # `"allocation\n{featureName}"`. SHA-256 over the UTF-8 bytes; the first
+    # 4 bytes read as a little-endian uint32; `pct = marker / 0xFFFFFFFF * 100`.
+    #
+    # @return [Float] Percentile in [0, 100]
+    def compute_percentile(identity, seed, feature_key, ignore_case)
+      user_id = identity.to_s
+      user_id = user_id.downcase if ignore_case
+      hint = seed.nil? ? "allocation\n#{feature_key}" : seed.to_s
+      context_id = "#{user_id}\n#{hint}"
+
+      digest = Digest::SHA256.digest(context_id)
+      marker = digest.byteslice(0, 4).unpack1("V") # little-endian uint32; unpack1("V") is endian-explicit
+      (marker.to_f / 0xFFFFFFFF) * 100.0
+    end
+
+    def build_assignment(variant_name, variants, base_enabled, reason)
+      variant = Array(variants).find { |v| v.name == variant_name }
+      effective_enabled =
+        if variant&.enabled_override?
+          true
+        elsif variant&.disabled_override?
+          false
+        else
+          base_enabled
+        end
+
+      Assignment.new(
+        variant_name: variant_name,
+        configuration_value: variant&.configuration_value,
+        enabled: effective_enabled,
+        reason: reason
+      )
+    end
+  end
+end

data/lib/toggly/variant_result.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Assigned variant for a feature, returned by `Client#get_variant`.
+  #
+  # Assignment is computed locally from the feature's catalog
+  # `variants` / `allocation` (see {VariantAllocator}), matching
+  # `Microsoft.FeatureManagement`'s `IVariantFeatureManager` bit-for-bit.
+  # There is no network round-trip: this is not the `enable_variants`
+  # dual-rail from earlier releases (removed; see CHANGELOG).
+  class VariantResult
+    # @return [String] Variant name
+    attr_reader :name
+
+    # @return [Object, nil] Untyped configuration payload for this variant
+    attr_reader :configuration_value
+
+    # @return [Boolean] Effective enabled flag for this feature/context after
+    #   the variant's `StatusOverride` is applied. This can differ from
+    #   `Client#enabled?`, which stays filter-based only; use this field when
+    #   you need MF-identical `GetVariantAsync`-style effective-enabled
+    #   semantics (e.g. a variant with `StatusOverride: "Enabled"` on an
+    #   otherwise-disabled feature).
+    attr_reader :enabled
+
+    # @return [String] Assignment reason: "User" | "Group" | "Percentile" |
+    #   "DefaultWhenEnabled" | "DefaultWhenDisabled"
+    attr_reader :reason
+
+    def initialize(name:, configuration_value: nil, enabled: true, reason: nil)
+      @name = name
+      @configuration_value = configuration_value
+      @enabled = enabled
+      @reason = reason
+    end
+
+    # @return [Hash]
+    def to_h
+      { name: @name, configuration_value: @configuration_value, enabled: @enabled, reason: @reason }
+    end
+
+    def ==(other)
+      other.is_a?(VariantResult) &&
+        @name == other.name &&
+        @configuration_value == other.configuration_value &&
+        @enabled == other.enabled &&
+        @reason == other.reason
+    end
+    alias eql? ==
+  end
+end

data/lib/toggly/version.rb

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

data/lib/toggly.rb

@@ -9,8 +9,10 @@ require_relative "toggly/sticky_hash"
 require_relative "toggly/user_agent_parser"
 require_relative "toggly/context"
 require_relative "toggly/errors"
+require_relative "toggly/feature_variant"
 require_relative "toggly/feature_definition"
-require_relative "toggly/evaluated_variant"
+require_relative "toggly/variant_allocator"
+require_relative "toggly/variant_result"
 require_relative "toggly/evaluators/base"
 require_relative "toggly/evaluators/segment_helpers"
 require_relative "toggly/evaluators/always_on"
@@ -104,6 +106,29 @@ module Toggly
       !enabled?(feature_key, context: context)
     end
 
+    # Assign a catalog-local variant using the global client.
+    # See {Client#get_variant}.
+    #
+    # @param feature_key [String, Symbol]
+    # @param context [Context, nil]
+    # @return [VariantResult, nil]
+    def get_variant(feature_key, context: nil)
+      raise Error, "Toggly not configured. Call Toggly.configure first." unless @client
+
+      @client.get_variant(feature_key, context: context)
+    end
+
+    # Configuration value for the assigned variant. See {Client#get_variant_value}.
+    #
+    # @param feature_key [String, Symbol]
+    # @param context [Context, nil]
+    # @return [Object, nil]
+    def get_variant_value(feature_key, context: nil)
+      raise Error, "Toggly not configured. Call Toggly.configure first." unless @client
+
+      @client.get_variant_value(feature_key, context: context)
+    end
+
     # Reset the global client (mainly for testing)
     def reset!
       @client&.close

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toggly
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Ops.ai
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies: []
 description: High-performance Ruby SDK for Toggly feature flag management. Works with
   or without Toggly.io.
@@ -31,7 +31,6 @@ files:
 - lib/toggly/definitions_provider.rb
 - lib/toggly/entity_context.rb
 - lib/toggly/errors.rb
-- lib/toggly/evaluated_variant.rb
 - lib/toggly/evaluation_engine.rb
 - lib/toggly/evaluators/always_off.rb
 - lib/toggly/evaluators/always_on.rb
@@ -49,6 +48,7 @@ files:
 - lib/toggly/evaluators/time_window.rb
 - lib/toggly/evaluators/user_claims.rb
 - lib/toggly/feature_definition.rb
+- lib/toggly/feature_variant.rb
 - lib/toggly/http_request_mapper.rb
 - lib/toggly/registry.rb
 - lib/toggly/request_context.rb
@@ -67,6 +67,8 @@ files:
 - lib/toggly/telemetry/runtime_flush.rb
 - lib/toggly/telemetry/usage_batcher.rb
 - lib/toggly/user_agent_parser.rb
+- lib/toggly/variant_allocator.rb
+- lib/toggly/variant_result.rb
 - lib/toggly/version.rb
 - proto/metrics.proto
 - proto/usage.proto

data/lib/toggly/evaluated_variant.rb

@@ -1,88 +0,0 @@
-# frozen_string_literal: true
-
-module Toggly
-  # Server-evaluated variant entry for a single feature flag, as returned by
-  # `evaluated-variants-signed`. This is distinct from `FeatureDefinition`
-  # (client-side rules): the server has already picked the winning variant.
-  class EvaluatedVariantDef
-    # @return [Boolean] Whether the feature is enabled for this assignment
-    attr_reader :enabled
-
-    # @return [String, nil] Assigned variant name, if any
-    attr_reader :variant
-
-    # @return [Object, nil] Configuration payload for the variant (shape depends on the feature)
-    attr_reader :configuration_value
-
-    def initialize(enabled:, variant: nil, configuration_value: nil)
-      @enabled = enabled ? true : false
-      @variant = variant
-      @configuration_value = configuration_value
-    end
-
-    # Create from a hash (API response or snapshot; camelCase or snake_case).
-    #
-    # @param hash [Hash]
-    # @return [EvaluatedVariantDef]
-    def self.from_hash(hash)
-      hash = symbolize_keys(hash)
-      configuration_value = if hash.key?(:configurationValue)
-                              hash[:configurationValue]
-                            else
-                              hash[:configuration_value]
-                            end
-
-      new(
-        enabled: hash[:enabled],
-        variant: hash[:variant],
-        configuration_value: configuration_value
-      )
-    end
-
-    # Convert to a hash for serialization (snapshot persistence).
-    #
-    # @return [Hash]
-    def to_h
-      {
-        enabled: @enabled,
-        variant: @variant,
-        configuration_value: @configuration_value
-      }
-    end
-
-    def ==(other)
-      other.is_a?(EvaluatedVariantDef) &&
-        @enabled == other.enabled &&
-        @variant == other.variant &&
-        @configuration_value == other.configuration_value
-    end
-    alias eql? ==
-
-    def self.symbolize_keys(hash)
-      return hash unless hash.is_a?(Hash)
-
-      hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
-    end
-    private_class_method :symbolize_keys
-  end
-
-  # Assigned variant name and configuration value for a feature, returned by
-  # `Client#get_variant` when `Config#enable_variants` is true.
-  class VariantResult
-    # @return [String] Variant name assigned by the server
-    attr_reader :name
-
-    # @return [Object, nil] Optional configuration payload for the variant
-    attr_reader :configuration_value
-
-    def initialize(name:, configuration_value: nil)
-      @name = name
-      @configuration_value = configuration_value
-    end
-
-    # @return [Hash]
-    def to_h
-      { name: @name, configuration_value: @configuration_value }
-    end
-  end
-end