toggly 0.6.0 → 1.1.0

data/lib/toggly/definitions_provider.rb

@@ -17,12 +17,6 @@ module Toggly
     # Result of one HTTP definitions fetch with cache telemetry outcome.
     FetchResult = Struct.new(:definitions, :cache_outcome, keyword_init: true)
 
-    # Result of one HTTP evaluated-variants fetch with cache telemetry outcome.
-    VariantFetchResult = Struct.new(:variants, :cache_outcome, keyword_init: true)
-
-    # Maximum number of string claims sent on the evaluated-variants-signed wire.
-    MAX_VARIANT_CLAIMS = 20
-
     # Fallback HTTP refresh interval when WebSocket is connected (20 minutes)
     FALLBACK_REFRESH_INTERVAL = 20 * 60
 
@@ -43,13 +37,6 @@ module Toggly
       @last_modified = nil
       @last_ts = 0
 
-      # Evaluated-variants rail state — separate ETag/Last-Modified/timestamp
-      # namespace from definitions so the two rails never cross-invalidate.
-      @variant_etag = nil
-      @variant_last_modified = nil
-      @variant_last_ts = 0
-      @variant_identity = config.variant_identity
-
       # WebSocket state
       @ws = nil
       @ws_connected = false
@@ -90,56 +77,6 @@ module Toggly
       @last_ts = 0
     end
 
-    # Fetch server-evaluated variants from `evaluated-variants-signed`.
-    # Independent ETag/timestamp cache from {#fetch} (separate rail).
-    #
-    # @param force [Boolean] Force fetch even if cached
-    # @return [VariantFetchResult] variants (Hash or nil) plus :hit / :miss outcome
-    # @raise [NetworkError] On network failures
-    # @raise [DefinitionsError] On API errors
-    def fetch_variants(force: false)
-      return VariantFetchResult.new(variants: nil, cache_outcome: :hit) if @config.offline_mode?
-
-      uri = URI.parse(build_variant_request_url)
-      http = build_http(uri)
-      request = build_variant_request(uri, force)
-
-      response = http.request(request)
-      handle_variant_response(response)
-    rescue Net::OpenTimeout, Net::ReadTimeout => e
-      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
-
-    # Update the `userId` sent to `evaluated-variants-signed`. Distinct from
-    # any per-call `Context#identity` used for local rule evaluation. Named
-    # as an action (not `variant_identity=`) because it also invalidates the
-    # variants cache — it is not a passive attribute writer.
-    #
-    # @param identity [String, nil]
-    # @return [Boolean] true if the identity changed (cache invalidated)
-    # rubocop:disable-next Naming/AccessorMethodName
-    def set_variant_identity(identity)
-      normalized = identity&.to_s
-      return false if normalized == @variant_identity
-
-      @variant_identity = normalized
-      reset_variant_cache
-      true
-    end
-
-    # Reset cached variant headers/timestamp (force full fetch next time)
-    def reset_variant_cache
-      @variant_etag = nil
-      @variant_last_modified = nil
-      @variant_last_ts = 0
-    end
-
     # Check whether the periodic refresh should be skipped because the
     # WebSocket connection is active and the fallback interval has not elapsed.
     #
@@ -299,110 +236,6 @@ module Toggly
       @last_modified = last_modified if last_modified && !last_modified.empty?
     end
 
-    def build_variant_request_url
-      pairs = variant_query_pairs
-      base = @config.variants_endpoint
-      pairs.empty? ? base : "#{base}?#{URI.encode_www_form(pairs)}"
-    end
-
-    def variant_query_pairs
-      pairs = []
-      pairs << ["userId", @variant_identity] if @variant_identity && !@variant_identity.empty?
-
-      Array(@config.variant_groups).each do |group|
-        next unless group.is_a?(String)
-
-        trimmed = group.strip
-        pairs << ["g", trimmed] unless trimmed.empty?
-      end
-
-      normalized_claims = {}
-      (@config.variant_claims || {}).each do |key, value|
-        next unless key.is_a?(String) && value.is_a?(String)
-        next if key.empty? || value.empty?
-
-        normalized_claims[key] = value
-      end
-      normalized_claims.keys.sort.first(MAX_VARIANT_CLAIMS).each do |key|
-        pairs << ["claim.#{key}", normalized_claims[key]]
-      end
-
-      pairs
-    end
-
-    def build_variant_request(uri, force)
-      request = Net::HTTP::Get.new(uri)
-      request["Accept"] = "application/json"
-      request["User-Agent"] = "toggly-ruby/#{Toggly::VERSION}"
-      request["X-App-Version"] = @config.app_version if @config.app_version
-      request["X-Instance-Name"] = @config.instance_name if @config.instance_name
-
-      unless force
-        request["If-None-Match"] = @variant_etag if @variant_etag
-        request["If-Modified-Since"] = @variant_last_modified if @variant_last_modified
-      end
-
-      request
-    end
-
-    def handle_variant_response(response)
-      status = response.code.to_i
-      response_etag = response["ETag"]
-      response_lm = response["Last-Modified"]
-      kind = DefinitionCache.classify_http(
-        status,
-        @variant_etag,
-        response_etag,
-        existing_last_modified: @variant_last_modified,
-        response_last_modified: response_lm
-      )
-
-      case kind
-      when :not_modified
-        log_debug("Evaluated variants not modified")
-        VariantFetchResult.new(variants: nil, cache_outcome: :hit)
-      when :same_revision
-        log_debug("Evaluated variants revision matches existing (ETag or Last-Modified)")
-        store_variant_revision_headers(response_etag, response_lm)
-        VariantFetchResult.new(variants: nil, cache_outcome: :hit)
-      when :new_content
-        handle_new_variant_content(response, response_etag, response_lm)
-      when :error_status
-        handle_error_status(status, response, resource: "evaluated variants")
-      end
-    end
-
-    def handle_new_variant_content(response, response_etag, response_lm)
-      data = JSON.parse(response.body)
-      signed_ts = extract_signed_timestamp(data)
-      if DefinitionCache.cached_signed_timestamp?(@variant_last_ts, signed_ts)
-        log_debug("Evaluated variants signed timestamp is not newer than cached revision")
-        store_variant_revision_headers(response_etag, response_lm)
-        return VariantFetchResult.new(variants: nil, cache_outcome: :hit)
-      end
-
-      variants = parse_variant_defs(data)
-      store_variant_revision_headers(response_etag, response_lm)
-      @variant_last_ts = signed_ts if signed_ts&.positive?
-      VariantFetchResult.new(variants: variants, cache_outcome: :miss)
-    rescue JSON::ParserError => e
-      raise DefinitionsError, "Failed to parse evaluated variants: #{e.message}"
-    end
-
-    def store_variant_revision_headers(etag, last_modified)
-      @variant_etag = etag if etag && !etag.empty?
-      @variant_last_modified = last_modified if last_modified && !last_modified.empty?
-    end
-
-    def parse_variant_defs(data)
-      raw = data.is_a?(Hash) ? data["defs"] : nil
-      return {} unless raw.is_a?(Hash)
-
-      raw.each_with_object({}) do |(key, value), hash|
-        hash[key] = EvaluatedVariantDef.from_hash(value) if value.is_a?(Hash)
-      end
-    end
-
     def extract_signed_timestamp(data)
       return nil unless data.is_a?(Hash)
 

data/lib/toggly/feature_definition.rb

@@ -35,6 +35,12 @@ module Toggly
     # @return [String, nil] Feature description
     attr_reader :description
 
+    # @return [Array<FeatureVariant>] Named variants for MF-parity assignment
+    attr_reader :variants
+
+    # @return [FeatureVariantAllocation, nil] Allocation rules for variant assignment
+    attr_reader :allocation
+
     # Feature types
     TYPES = %w[Release Experiment Ops Permission].freeze
 
@@ -50,7 +56,9 @@ module Toggly
       updated_at: nil,
       requirement_type: "Any",
       context_kind: nil,
-      context_requirement_type: nil
+      context_requirement_type: nil,
+      variants: [],
+      allocation: nil
     )
       @feature_key = feature_key.to_s
       @feature_type = validate_type(feature_type)
@@ -63,6 +71,8 @@ module Toggly
       @requirement_type = requirement_type || "Any"
       @context_kind = context_kind
       @context_requirement_type = context_requirement_type
+      @variants = Array(variants)
+      @allocation = allocation
     end
 
     # Create from a hash (e.g., from JSON)
@@ -83,6 +93,9 @@ module Toggly
                   !rules.empty?
                 end
 
+      variants = Array(hash[:variants]).map { |v| FeatureVariant.from_hash(v) }
+      allocation = FeatureVariantAllocation.from_hash(hash[:allocation])
+
       new(
         feature_key: hash[:featureKey] || hash[:feature_key],
         feature_type: hash[:featureType] || hash[:feature_type] || "Release",
@@ -94,7 +107,9 @@ module Toggly
         updated_at: hash[:updatedAt] || hash[:updated_at],
         requirement_type: hash[:requirementType] || hash[:requirement_type] || "Any",
         context_kind: hash[:contextKind] || hash[:context_kind],
-        context_requirement_type: hash[:contextRequirementType] || hash[:context_requirement_type]
+        context_requirement_type: hash[:contextRequirementType] || hash[:context_requirement_type],
+        variants: variants,
+        allocation: allocation
       )
     end
 
@@ -110,7 +125,9 @@ module Toggly
         metadata: @metadata,
         description: @description,
         created_at: @created_at&.iso8601,
-        updated_at: @updated_at&.iso8601
+        updated_at: @updated_at&.iso8601,
+        variants: @variants.map(&:to_h),
+        allocation: @allocation&.to_h
       }
     end
 

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