toggly 0.6.0 → 1.0.0

data/lib/toggly/feature_variant.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Toggly
+  # A single named variant of a feature flag, as sent on the catalog
+  # (`definitions` / `definitions-signed`) wire alongside `filters`.
+  #
+  # Matches the shape produced by `Microsoft.FeatureManagement`'s
+  # `VariantDefinition` (`Name`, `ConfigurationValue`, `StatusOverride`).
+  class FeatureVariant
+    # Valid `StatusOverride` values (MF `StatusOverride` enum as strings).
+    STATUS_OVERRIDES = %w[None Enabled Disabled].freeze
+
+    # @return [String] Variant name
+    attr_reader :name
+
+    # @return [Object, nil] Untyped configuration payload for this variant
+    attr_reader :configuration_value
+
+    # @return [String] "None" | "Enabled" | "Disabled"
+    attr_reader :status_override
+
+    def initialize(name:, configuration_value: nil, status_override: "None")
+      @name = name.to_s
+      @configuration_value = configuration_value
+      @status_override = STATUS_OVERRIDES.include?(status_override.to_s) ? status_override.to_s : "None"
+    end
+
+    # @param hash [Hash] Variant hash (camelCase wire or snake_case snapshot)
+    # @return [FeatureVariant]
+    def self.from_hash(hash)
+      hash = symbolize_keys(hash)
+      configuration_value = if hash.key?(:configurationValue)
+                              hash[:configurationValue]
+                            else
+                              hash[:configuration_value]
+                            end
+
+      new(
+        name: hash[:name],
+        configuration_value: configuration_value,
+        status_override: hash[:statusOverride] || hash[:status_override] || "None"
+      )
+    end
+
+    # @return [Boolean] True when this variant forces the feature to be
+    #   reported enabled regardless of the base filter-evaluated state.
+    def enabled_override?
+      @status_override == "Enabled"
+    end
+
+    # @return [Boolean] True when this variant forces the feature to be
+    #   reported disabled regardless of the base filter-evaluated state.
+    def disabled_override?
+      @status_override == "Disabled"
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        name: @name,
+        configuration_value: @configuration_value,
+        status_override: @status_override
+      }
+    end
+
+    def ==(other)
+      other.is_a?(FeatureVariant) &&
+        @name == other.name &&
+        @configuration_value == other.configuration_value &&
+        @status_override == other.status_override
+    end
+    alias eql? ==
+
+    def hash
+      [@name, @configuration_value, @status_override].hash
+    end
+
+    def self.symbolize_keys(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+    end
+    private_class_method :symbolize_keys
+  end
+
+  # Allocation rules for assigning variants to users/groups/percentile
+  # buckets, matching `Microsoft.FeatureManagement`'s `Allocation` schema.
+  class FeatureVariantAllocation
+    # @return [String, nil] Variant assigned when the feature is enabled and
+    #   no user/group/percentile allocation matched.
+    attr_reader :default_when_enabled
+
+    # @return [String, nil] Variant assigned when the feature is disabled.
+    attr_reader :default_when_disabled
+
+    # @return [String, nil] Seed for the percentile hash; falls back to
+    #   "allocation\n{featureName}" when nil.
+    attr_reader :seed
+
+    # @return [Array<Hash>] `[{ variant:, users: [...] }, ...]`
+    attr_reader :user
+
+    # @return [Array<Hash>] `[{ variant:, groups: [...] }, ...]`
+    attr_reader :group
+
+    # @return [Array<Hash>] `[{ variant:, from:, to: }, ...]`
+    attr_reader :percentile
+
+    def initialize(default_when_enabled: nil, default_when_disabled: nil, seed: nil, user: [], group: [], percentile: [])
+      @default_when_enabled = default_when_enabled
+      @default_when_disabled = default_when_disabled
+      @seed = seed
+      @user = Array(user)
+      @group = Array(group)
+      @percentile = Array(percentile)
+    end
+
+    # @param hash [Hash, nil]
+    # @return [FeatureVariantAllocation, nil] nil when +hash+ is nil (no allocation configured)
+    def self.from_hash(hash)
+      return nil unless hash.is_a?(Hash)
+
+      hash = symbolize_keys(hash)
+      new(
+        default_when_enabled: hash[:defaultWhenEnabled] || hash[:default_when_enabled],
+        default_when_disabled: hash[:defaultWhenDisabled] || hash[:default_when_disabled],
+        seed: hash[:seed],
+        user: parse_entries(hash[:user], :users),
+        group: parse_entries(hash[:group], :groups),
+        percentile: parse_percentile_entries(hash[:percentile])
+      )
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        default_when_enabled: @default_when_enabled,
+        default_when_disabled: @default_when_disabled,
+        seed: @seed,
+        user: @user,
+        group: @group,
+        percentile: @percentile
+      }
+    end
+
+    def ==(other)
+      other.is_a?(FeatureVariantAllocation) &&
+        @default_when_enabled == other.default_when_enabled &&
+        @default_when_disabled == other.default_when_disabled &&
+        @seed == other.seed &&
+        @user == other.user &&
+        @group == other.group &&
+        @percentile == other.percentile
+    end
+    alias eql? ==
+
+    def hash
+      [@default_when_enabled, @default_when_disabled, @seed, @user, @group, @percentile].hash
+    end
+
+    def self.parse_entries(raw, members_key)
+      Array(raw).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        entry = symbolize_keys(entry)
+        { variant: entry[:variant], members_key => Array(entry[members_key]).map(&:to_s) }
+      end
+    end
+    private_class_method :parse_entries
+
+    def self.parse_percentile_entries(raw)
+      Array(raw).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        entry = symbolize_keys(entry)
+        { variant: entry[:variant], from: entry[:from].to_f, to: entry[:to].to_f }
+      end
+    end
+    private_class_method :parse_percentile_entries
+
+    def self.symbolize_keys(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+    end
+    private_class_method :symbolize_keys
+  end
+end

data/lib/toggly/snapshot_providers/base.rb

@@ -40,21 +40,6 @@ module Toggly
         false
       end
 
-      # Save evaluated variants snapshot (dual-rail, used when
-      # `config.enable_variants` is true). Default: no-op. Override in
-      # subclasses to persist variants across restarts.
-      #
-      # @param variants [Hash<String, EvaluatedVariantDef>] Variants to save
-      # @param metadata [Hash] Optional metadata
-      def save_variants(_variants, _metadata = {}); end
-
-      # Load evaluated variants snapshot (dual-rail).
-      #
-      # @return [Hash, nil] Hash with :variants and :metadata, or nil if not available
-      def load_variants
-        nil
-      end
-
       protected
 
       # Serialize definitions to a storable format
@@ -77,26 +62,6 @@ module Toggly
           hash[definition.feature_key] = definition
         end
       end
-
-      # Serialize evaluated variants to a storable format
-      #
-      # @param variants [Hash<String, EvaluatedVariantDef>] Variants
-      # @return [Hash<String, Hash>]
-      def serialize_variants(variants)
-        variants.transform_values(&:to_h)
-      end
-
-      # Deserialize evaluated variants from stored format
-      #
-      # @param data [Hash<String, Hash>] Serialized variants
-      # @return [Hash<String, EvaluatedVariantDef>]
-      def deserialize_variants(data)
-        return {} unless data.is_a?(Hash)
-
-        data.each_with_object({}) do |(key, value), hash|
-          hash[key.to_s] = EvaluatedVariantDef.from_hash(value)
-        end
-      end
     end
   end
 end

data/lib/toggly/snapshot_providers/file.rb

@@ -12,14 +12,10 @@ module Toggly
       # @return [String] Path to the snapshot file
       attr_reader :path
 
-      # @return [String] Path to the evaluated-variants snapshot file (dual-rail)
-      attr_reader :variants_path
-
       # @param path [String] Path to the snapshot file
       def initialize(path:)
         super()
         @path = path
-        @variants_path = derive_variants_path(path)
         @mutex = Mutex.new
       end
 
@@ -70,7 +66,6 @@ module Toggly
       def clear
         @mutex.synchronize do
           FileUtils.rm_f(@path)
-          FileUtils.rm_f(@variants_path)
         end
       rescue StandardError => e
         raise SnapshotError, "Failed to clear snapshot: #{e.message}"
@@ -83,48 +78,6 @@ module Toggly
         ::File.exist?(@path)
       end
 
-      # Save evaluated variants to file using atomic write (dual-rail)
-      #
-      # @param variants [Hash<String, EvaluatedVariantDef>] Variants
-      # @param metadata [Hash] Optional metadata
-      def save_variants(variants, metadata = {})
-        @mutex.synchronize do
-          ensure_directory_exists
-
-          data = {
-            "variants" => serialize_variants(variants),
-            "metadata" => metadata.merge("saved_at" => Time.now.utc.iso8601)
-          }
-
-          temp_path = "#{@variants_path}.tmp"
-          ::File.write(temp_path, JSON.pretty_generate(data))
-          ::File.rename(temp_path, @variants_path)
-        end
-      rescue StandardError => e
-        raise SnapshotError, "Failed to save variants snapshot: #{e.message}"
-      end
-
-      # Load evaluated variants from file (dual-rail)
-      #
-      # @return [Hash, nil] Hash with :variants and :metadata
-      def load_variants
-        @mutex.synchronize do
-          return nil unless ::File.exist?(@variants_path)
-
-          content = ::File.read(@variants_path)
-          data = JSON.parse(content)
-
-          {
-            variants: deserialize_variants(data["variants"]),
-            metadata: symbolize_keys(data["metadata"] || {})
-          }
-        end
-      rescue JSON::ParserError => e
-        raise SnapshotError, "Failed to parse variants snapshot: #{e.message}"
-      rescue StandardError => e
-        raise SnapshotError, "Failed to load variants snapshot: #{e.message}"
-      end
-
       private
 
       def ensure_directory_exists
@@ -132,13 +85,6 @@ module Toggly
         FileUtils.mkdir_p(dir) unless ::File.directory?(dir)
       end
 
-      def derive_variants_path(path)
-        dir = ::File.dirname(path)
-        ext = ::File.extname(path)
-        base = ::File.basename(path, ext)
-        ::File.join(dir, "#{base}_variants#{ext}")
-      end
-
       def symbolize_keys(hash)
         return {} unless hash.is_a?(Hash)
 

data/lib/toggly/snapshot_providers/memory.rb

@@ -9,7 +9,6 @@ module Toggly
       def initialize
         super
         @data = nil
-        @variants_data = nil
         @mutex = Mutex.new
       end
 
@@ -44,7 +43,6 @@ module Toggly
       def clear
         @mutex.synchronize do
           @data = nil
-          @variants_data = nil
         end
       end
 
@@ -56,33 +54,6 @@ module Toggly
           !@data.nil?
         end
       end
-
-      # Save evaluated variants to memory (dual-rail)
-      #
-      # @param variants [Hash<String, EvaluatedVariantDef>] Variants
-      # @param metadata [Hash] Optional metadata
-      def save_variants(variants, metadata = {})
-        @mutex.synchronize do
-          @variants_data = {
-            variants: serialize_variants(variants),
-            metadata: metadata.merge(saved_at: Time.now.utc.iso8601)
-          }
-        end
-      end
-
-      # Load evaluated variants from memory (dual-rail)
-      #
-      # @return [Hash, nil] Hash with :variants and :metadata
-      def load_variants
-        @mutex.synchronize do
-          return nil unless @variants_data
-
-          {
-            variants: deserialize_variants(@variants_data[:variants]),
-            metadata: @variants_data[:metadata]
-          }
-        end
-      end
     end
   end
 end

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toggly
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Ops.ai
@@ -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