amplitude-experiment 1.3.1 → 1.5.0

data/lib/experiment/local/client.rb

@@ -3,8 +3,7 @@ require 'logger'
 require_relative '../../amplitude'
 
 module AmplitudeExperiment
-  FLAG_TYPE_MUTUAL_EXCLUSION_GROUP = 'mutual_exclusion_group'.freeze
-  FLAG_TYPE_HOLDOUT_GROUP = 'holdout-group'.freeze
+  FLAG_TYPE_MUTUAL_EXCLUSION_GROUP = 'mutual-exclusion-group'.freeze
   # Main client for fetching variant data.
   class LocalEvaluationClient
     # Creates a new Experiment Client instance.
@@ -24,11 +23,24 @@ module AmplitudeExperiment
                       else
                         Logger::INFO
                       end
-      @fetcher = LocalEvaluationFetcher.new(api_key, @logger, @config.server_url)
       raise ArgumentError, 'Experiment API key is empty' if @api_key.nil? || @api_key.empty?
 
       @assignment_service = nil
       @assignment_service = AssignmentService.new(AmplitudeAnalytics::Amplitude.new(config.assignment_config.api_key, configuration: config.assignment_config), AssignmentFilter.new(config.assignment_config.cache_capacity)) if config&.assignment_config
+
+      @cohort_storage = InMemoryCohortStorage.new
+      @flag_config_storage = InMemoryFlagConfigStorage.new
+      @flag_config_fetcher = LocalEvaluationFetcher.new(@api_key, @logger, @config.server_url)
+      @cohort_loader = nil
+      unless @config.cohort_sync_config.nil?
+        @cohort_download_api = DirectCohortDownloadApi.new(@config.cohort_sync_config.api_key,
+                                                           @config.cohort_sync_config.secret_key,
+                                                           @config.cohort_sync_config.max_cohort_size,
+                                                           @config.cohort_sync_config.cohort_server_url,
+                                                           @logger)
+        @cohort_loader = CohortLoader.new(@cohort_download_api, @cohort_storage)
+      end
+      @deployment_runner = DeploymentRunner.new(@config, @flag_config_fetcher, @flag_config_storage, @cohort_storage, @logger, @cohort_loader)
     end
 
     # Locally evaluates flag variants for a user.
@@ -37,18 +49,37 @@ module AmplitudeExperiment
     # @param [String[]] flag_keys The flags to evaluate with the user. If empty, all flags from the flag cache are evaluated
     #
     # @return [Hash[String, Variant]] The evaluated variants
+    # @deprecated Please use {evaluate_v2} instead
     def evaluate(user, flag_keys = [])
-      flags = @flags_mutex.synchronize do
-        @flags
-      end
+      variants = evaluate_v2(user, flag_keys)
+      AmplitudeExperiment.filter_default_variants(variants)
+    end
+
+    # Locally evaluates flag variants for a user.
+    #  This function will only evaluate flags for the keys specified in the flag_keys argument. If flag_keys is
+    #  missing or None, all flags are evaluated. This function differs from evaluate as it will return a default
+    #  variant object if the flag was evaluated but the user was not assigned (i.e. off).
+    #
+    # @param [User] user The user to evaluate
+    # @param [String[]] flag_keys The flags to evaluate with the user, if empty all flags are evaluated
+    # @return [Hash[String, Variant]] The evaluated variants
+    def evaluate_v2(user, flag_keys = [])
+      flags = @flag_config_storage.flag_configs
       return {} if flags.nil?
 
-      user_str = user.to_json
+      sorted_flags = AmplitudeExperiment.topological_sort(flags, flag_keys.to_set)
+      required_cohorts_in_storage(sorted_flags)
+      flags_json = sorted_flags.to_json
+      user = enrich_user_with_cohorts(user, flags) if @config.cohort_sync_config
+      context = AmplitudeExperiment.user_to_evaluation_context(user)
+      context_json = context.to_json
 
-      @logger.debug("[Experiment] Evaluate: User: #{user_str} - Rules: #{flags}") if @config.debug
-      result = evaluation(flags, user_str)
+      @logger.debug("[Experiment] Evaluate: User: #{context_json} - Rules: #{flags}") if @config.debug
+      result = evaluation(flags_json, context_json)
       @logger.debug("[Experiment] evaluate - result: #{result}") if @config.debug
-      parse_results(result, flag_keys, user)
+      variants = AmplitudeExperiment.evaluation_variants_json_to_variants(result)
+      @assignment_service&.track(Assignment.new(user, variants))
+      variants
     end
 
     # Fetch initial flag configurations and start polling for updates.
@@ -57,49 +88,62 @@ module AmplitudeExperiment
       return if @is_running
 
       @logger.debug('[Experiment] poller - start') if @debug
-      run
+      @deployment_runner.start
     end
 
     # Stop polling for flag configurations. Close resource like connection pool with client
     def stop
-      @poller_thread&.exit
       @is_running = false
-      @poller_thread = nil
+      @deployment_runner.stop
     end
 
     private
 
-    def parse_results(result, flag_keys, user)
-      variants = {}
-      assignments = {}
-      result.each do |key, value|
-        included = flag_keys.empty? || flag_keys.include?(key)
-        if !value['isDefaultVariant'] && included
-          variant_key = value['variant']['key']
-          variant_payload = value['variant']['payload']
-          variants.store(key, Variant.new(variant_key, variant_payload))
-        end
-
-        assignments[key] = value if included || value['type'] == FLAG_TYPE_MUTUAL_EXCLUSION_GROUP || value['type'] == FLAG_TYPE_HOLDOUT_GROUP
+    def required_cohorts_in_storage(flag_configs)
+      stored_cohort_ids = @cohort_storage.cohort_ids
+
+      flag_configs.each do |flag|
+        flag_cohort_ids = AmplitudeExperiment.get_all_cohort_ids_from_flag(flag)
+        missing_cohorts = flag_cohort_ids - stored_cohort_ids
+
+        next unless missing_cohorts.any?
+
+        # Convert cohort IDs to a comma-separated string
+        cohort_ids_str = "[#{flag_cohort_ids.map(&:to_s).join(', ')}]"
+        missing_cohorts_str = "[#{missing_cohorts.map(&:to_s).join(', ')}]"
+
+        message = if @config.cohort_sync_config
+                    "Evaluating flag #{flag['key']} dependent on cohorts #{cohort_ids_str} without #{missing_cohorts_str} in storage"
+                  else
+                    "Evaluating flag #{flag['key']} dependent on cohorts #{cohort_ids_str} without cohort syncing configured"
+                  end
+
+        @logger.warn(message)
       end
-      @assignment_service&.track(Assignment.new(user, assignments))
-      variants
     end
 
-    def run
-      @is_running = true
-      begin
-        flags = @fetcher.fetch_v1
-        @flags_mutex.synchronize do
-          @flags = flags
-        end
-      rescue StandardError => e
-        @logger.error("[Experiment] Flag poller - error: #{e.message}")
+    def enrich_user_with_cohorts(user, flag_configs)
+      grouped_cohort_ids = AmplitudeExperiment.get_grouped_cohort_ids_from_flags(flag_configs)
+
+      if grouped_cohort_ids.key?(USER_GROUP_TYPE)
+        user_cohort_ids = grouped_cohort_ids[USER_GROUP_TYPE]
+        user.cohort_ids = Array(@cohort_storage.get_cohorts_for_user(user.user_id, user_cohort_ids)) if user_cohort_ids && user.user_id
       end
-      @poller_thread = Thread.new do
-        sleep(@config.flag_config_polling_interval_millis / 1000.to_f)
-        run
+
+      user.groups&.each do |group_type, group_names|
+        group_name = group_names.first if group_names
+        next unless group_name
+
+        cohort_ids = grouped_cohort_ids[group_type] || []
+        next if cohort_ids.empty?
+
+        user.add_group_cohort_ids(
+          group_type,
+          group_name,
+          Array(@cohort_storage.get_cohorts_for_group(group_type, group_name, cohort_ids))
+        )
       end
+      user
     end
   end
 end

data/lib/experiment/local/config.rb

@@ -1,8 +1,14 @@
 module AmplitudeExperiment
+  module ServerZone
+    US = 'US'.freeze
+    EU = 'EU'.freeze
+  end
+
   # LocalEvaluationConfig
   class LocalEvaluationConfig
     # Default server url
     DEFAULT_SERVER_URL = 'https://api.lab.amplitude.com'.freeze
+    EU_SERVER_URL = 'https://flag.lab.eu.amplitude.com'.freeze
 
     # Set to true to log some extra information to the console.
     # @return [Boolean] the value of debug
@@ -12,6 +18,10 @@ module AmplitudeExperiment
     # @return [String] the value of server url
     attr_accessor :server_url
 
+    # Location of the Amplitude data center to get flags and cohorts from, US or EU
+    # @return [String] the value of server zone
+    attr_accessor :server_zone
+
     # The polling interval for flag configs.
     # @return [long] the value of flag config polling interval in million seconds
     attr_accessor :flag_config_polling_interval_millis
@@ -20,14 +30,28 @@ module AmplitudeExperiment
     # @return [AssignmentConfig] the config instance
     attr_accessor :assignment_config
 
+    # Configuration for downloading cohorts required for flag evaluation
+    # @return [CohortSyncConfig] the config instance
+    attr_accessor :cohort_sync_config
+
     # @param [Boolean] debug Set to true to log some extra information to the console.
     # @param [String] server_url The server endpoint from which to request variants.
+    # @param [String] server_zone Location of the Amplitude data center to get flags and cohorts from, US or EU
     # @param [Hash] bootstrap The value of bootstrap.
     # @param [long] flag_config_polling_interval_millis The value of flag config polling interval in million seconds.
-    def initialize(server_url: DEFAULT_SERVER_URL, bootstrap: {},
-                   flag_config_polling_interval_millis: 30_000, debug: false, assignment_config: nil)
+    # @param [AssignmentConfig] assignment_config Configuration for automatically tracking assignment events after an evaluation.
+    # @param [CohortSyncConfig] cohort_sync_config Configuration for downloading cohorts required for flag evaluation
+    def initialize(server_url: DEFAULT_SERVER_URL, server_zone: ServerZone::US, bootstrap: {},
+                   flag_config_polling_interval_millis: 30_000, debug: false, assignment_config: nil,
+                   cohort_sync_config: nil)
       @debug = debug || false
       @server_url = server_url
+      @server_zone = server_zone
+      @cohort_sync_config = cohort_sync_config
+      if server_url == DEFAULT_SERVER_URL && @server_zone == ServerZone::EU
+        @server_url = EU_SERVER_URL
+        @cohort_sync_config.cohort_server_url = EU_COHORT_SYNC_URL if @cohort_sync_config && @cohort_sync_config.cohort_server_url == DEFAULT_COHORT_SYNC_URL
+      end
       @bootstrap = bootstrap
       @flag_config_polling_interval_millis = flag_config_polling_interval_millis
       @assignment_config = assignment_config

data/lib/experiment/local/evaluation/evaluation.rb

@@ -57,11 +57,11 @@ module EvaluationInterop
   attach_function :libevaluation_interop_symbols, [], Libevaluation_interop_ExportedSymbols.by_ref
 end
 
-def evaluation(rule_json, user_json)
+def evaluation(rule_json, context_json)
   lib = EvaluationInterop.libevaluation_interop_symbols()
   evaluate = lib[:kotlin][:root][:evaluate]
   dispose = lib[:DisposeString]
-  result_raw = evaluate.call(rule_json, user_json)
+  result_raw = evaluate.call(rule_json, context_json)
   result_json = result_raw.read_string
   result = JSON.parse(result_json)
   dispose.call(result_raw)

data/lib/experiment/local/evaluation/lib/linuxArm64/libevaluation_interop_api.h

@@ -99,7 +99,7 @@ typedef struct {
   /* User functions. */
   struct {
     struct {
-      const char* (*evaluate)(const char* rules, const char* user);
+      const char* (*evaluate)(const char* flags, const char* context);
     } root;
   } kotlin;
 } libevaluation_interop_ExportedSymbols;

data/lib/experiment/local/evaluation/lib/linuxX64/libevaluation_interop_api.h

@@ -99,7 +99,7 @@ typedef struct {
   /* User functions. */
   struct {
     struct {
-      const char* (*evaluate)(const char* rules, const char* user);
+      const char* (*evaluate)(const char* flags, const char* context);
     } root;
   } kotlin;
 } libevaluation_interop_ExportedSymbols;

data/lib/experiment/local/evaluation/lib/macosArm64/libevaluation_interop_api.h

@@ -99,7 +99,7 @@ typedef struct {
   /* User functions. */
   struct {
     struct {
-      const char* (*evaluate)(const char* rules, const char* user);
+      const char* (*evaluate)(const char* flags, const char* context);
     } root;
   } kotlin;
 } libevaluation_interop_ExportedSymbols;

data/lib/experiment/local/evaluation/lib/macosX64/libevaluation_interop_api.h

@@ -99,7 +99,7 @@ typedef struct {
   /* User functions. */
   struct {
     struct {
-      const char* (*evaluate)(const char* rules, const char* user);
+      const char* (*evaluate)(const char* flags, const char* context);
     } root;
   } kotlin;
 } libevaluation_interop_ExportedSymbols;

data/lib/experiment/remote/client.rb

@@ -30,7 +30,7 @@ module AmplitudeExperiment
     # @param [User] user
     # @return [Hash] Variants Hash
     def fetch(user)
-      filter_default_variants(fetch_internal(user))
+      AmplitudeExperiment.filter_default_variants(fetch_internal(user))
     rescue StandardError => e
       @logger.error("[Experiment] Failed to fetch variants: #{e.message}")
       {}
@@ -144,30 +144,11 @@ module AmplitudeExperiment
       raise FetchError.new(response.code.to_i, "Fetch error response: status=#{response.code} #{response.message}") if response.code != '200'
 
       json = JSON.parse(response.body)
-      variants = parse_json_variants(json)
+      variants = AmplitudeExperiment.evaluation_variants_json_to_variants(json)
       @logger.debug("[Experiment] Fetched variants: #{variants}")
       variants
     end
 
-    # Parse JSON response hash
-    #
-    # @param [Hash] json
-    # @return [Hash] Hash with String => Variant
-    def parse_json_variants(json)
-      variants = {}
-      json.each do |key, value|
-        variant_value = ''
-        if value.key?('value')
-          variant_value = value.fetch('value')
-        elsif value.key?('key')
-          # value was previously under the "key" field
-          variant_value = value.fetch('key')
-        end
-        variants.store(key, Variant.new(variant_value, value.fetch('payload', nil), value.fetch('key', nil), value.fetch('metadata', nil)))
-      end
-      variants
-    end
-
     # @param [User] user
     # @return [User, Hash] user with library context
     def add_context(user)
@@ -181,18 +162,5 @@ module AmplitudeExperiment
 
       true
     end
-
-    def filter_default_variants(variants)
-      variants.each do |key, value|
-        default = value&.metadata&.fetch('default', nil)
-        deployed = value&.metadata&.fetch('deployed', nil)
-        default = false if default.nil?
-        deployed = true if deployed.nil?
-        variants.delete(key) if default || !deployed
-      end
-      variants
-    end
-
-    private :filter_default_variants
   end
 end

data/lib/experiment/user.rb

@@ -72,6 +72,22 @@ module AmplitudeExperiment
     # @return [Hash, nil] the value of user properties
     attr_accessor :user_properties
 
+    # Predefined field, must be manually provided
+    # @return [Hash, nil] the value of groups
+    attr_accessor :groups
+
+    # Predefined field, must be manually provided
+    # @return [Hash, nil] the value of group properties
+    attr_accessor :group_properties
+
+    # Cohort IDs for the user
+    # @return [Hash, nil] the value of cohort_ids
+    attr_accessor :cohort_ids
+
+    # Cohort IDs for the user's groups
+    # @return [Hash, nil] the value of group_cohort_ids
+    attr_accessor :group_cohort_ids
+
     # @param [String, nil] device_id Device ID for associating with an identity in Amplitude
     # @param [String, nil] user_id User ID for associating with an identity in Amplitude
     # @param [String, nil] country Predefined field, must be manually provided
@@ -89,9 +105,12 @@ module AmplitudeExperiment
     # @param [String, nil] carrier Predefined field, must be manually provided
     # @param [String, nil] library Predefined field, auto populated, can be manually overridden
     # @param [Hash, nil] user_properties Custom user properties
+    # @param [Hash, nil] groups List of groups the user belongs to
+    # @param [Hash, nil] group_properties Custom properties for groups
     def initialize(device_id: nil, user_id: nil, country: nil, city: nil, region: nil, dma: nil, ip_address: nil, language: nil,
                    platform: nil, version: nil, os: nil, device_manufacturer: nil, device_brand: nil,
-                   device_model: nil, carrier: nil, library: nil, user_properties: nil)
+                   device_model: nil, carrier: nil, library: nil, user_properties: nil, groups: nil, group_properties: nil,
+                   cohort_ids: nil, group_cohort_ids: nil)
       @device_id = device_id
       @user_id = user_id
       @country = country
@@ -109,30 +128,38 @@ module AmplitudeExperiment
       @carrier = carrier
       @library = library
       @user_properties = user_properties
+      @groups = groups
+      @group_properties = group_properties
+      @cohort_ids = cohort_ids
+      @group_cohort_ids = group_cohort_ids
     end
 
     # Return User as Hash.
     # @return [Hash] Hash object with user values
     def as_json(_options = {})
       {
-        device_id: @device_id,
-        user_id: @user_id,
-        country: @country,
-        city: @city,
-        region: @region,
-        dma: @dma,
-        ip_address: @ip_address,
-        language: @language,
-        platform: @platform,
-        version: @version,
-        os: @os,
-        device_manufacturer: @device_manufacturer,
-        device_brand: @device_brand,
-        device_model: @device_model,
-        carrier: @carrier,
-        library: @library,
-        user_properties: @user_properties
-      }
+        'device_id' => @device_id,
+        'user_id' => @user_id,
+        'country' => @country,
+        'city' => @city,
+        'region' => @region,
+        'dma' => @dma,
+        'ip_address' => @ip_address,
+        'language' => @language,
+        'platform' => @platform,
+        'version' => @version,
+        'os' => @os,
+        'device_manufacturer' => @device_manufacturer,
+        'device_brand' => @device_brand,
+        'device_model' => @device_model,
+        'carrier' => @carrier,
+        'library' => @library,
+        'user_properties' => @user_properties,
+        'groups' => @groups,
+        'group_properties' => @group_properties,
+        'cohort_ids' => @cohort_ids,
+        'group_cohort_ids' => @group_cohort_ids
+      }.compact
     end
 
     # Return user information as JSON string.
@@ -140,5 +167,12 @@ module AmplitudeExperiment
     def to_json(*options)
       as_json(*options).to_json(*options)
     end
+
+    def add_group_cohort_ids(group_type, group_name, cohort_ids)
+      @group_cohort_ids ||= {}
+
+      group_names = @group_cohort_ids[group_type] ||= {}
+      group_names[group_name] = cohort_ids
+    end
   end
 end

data/lib/experiment/util/flag_config.rb

@@ -0,0 +1,60 @@
+module AmplitudeExperiment
+  def self.cohort_filter?(condition)
+    ['set contains any', 'set does not contain any'].include?(condition['op']) &&
+      condition['selector'] &&
+      condition['selector'][-1] == 'cohort_ids'
+  end
+
+  def self.get_grouped_cohort_condition_ids(segment)
+    cohort_ids = {}
+    conditions = segment['conditions'] || []
+    conditions.each do |condition|
+      condition = condition[0]
+      next unless cohort_filter?(condition) && (condition['selector'][1].length > 2)
+
+      context_subtype = condition['selector'][1]
+      group_type =
+        if context_subtype == 'user'
+          USER_GROUP_TYPE
+        elsif condition['selector'].include?('groups')
+          condition['selector'][2]
+        else
+          next
+        end
+      cohort_ids[group_type] ||= Set.new
+      cohort_ids[group_type].merge(condition['values'])
+    end
+    cohort_ids
+  end
+
+  def self.get_grouped_cohort_ids_from_flag(flag)
+    cohort_ids = {}
+    segments = flag['segments'] || []
+    segments.each do |segment|
+      get_grouped_cohort_condition_ids(segment).each do |key, values|
+        cohort_ids[key] ||= Set.new
+        cohort_ids[key].merge(values)
+      end
+    end
+    cohort_ids
+  end
+
+  def self.get_all_cohort_ids_from_flag(flag)
+    get_grouped_cohort_ids_from_flag(flag).values.reduce(Set.new) { |acc, set| acc.merge(set) }
+  end
+
+  def self.get_grouped_cohort_ids_from_flags(flags)
+    cohort_ids = {}
+    flags.each do |_, flag|
+      get_grouped_cohort_ids_from_flag(flag).each do |key, values|
+        cohort_ids[key] ||= Set.new
+        cohort_ids[key].merge(values)
+      end
+    end
+    cohort_ids
+  end
+
+  def self.get_all_cohort_ids_from_flags(flags)
+    get_grouped_cohort_ids_from_flags(flags).values.reduce(Set.new) { |acc, set| acc.merge(set) }
+  end
+end

data/lib/experiment/util/poller.rb

@@ -0,0 +1,24 @@
+module AmplitudeExperiment
+  # Poller
+  class Poller
+    def initialize(interval_seconds, callback)
+      @interval_seconds = interval_seconds
+      @callback = callback
+    end
+
+    def start
+      @running = true
+      @thread = Thread.new do
+        while @running
+          @callback.call
+          sleep(@interval_seconds)
+        end
+      end
+    end
+
+    def stop
+      @running = false
+      @thread&.join
+    end
+  end
+end

data/lib/experiment/util/topological_sort.rb

@@ -0,0 +1,39 @@
+module AmplitudeExperiment
+  def self.topological_sort(flags, keys = nil, ordered: false)
+    available = flags.dup
+    result = []
+    starting_keys = keys.nil? || keys.empty? ? flags.keys : keys
+    # Used for testing to ensure consistency.
+    starting_keys.sort! if ordered && (keys.nil? || keys.empty?)
+
+    starting_keys.each do |flag_key|
+      traversal = parent_traversal(flag_key, available, Set.new)
+      result.concat(traversal) unless traversal.nil?
+    end
+    result
+  end
+
+  def self.parent_traversal(flag_key, available, path)
+    flag = available[flag_key]
+    return nil if flag.nil?
+
+    dependencies = flag['dependencies']
+    if dependencies.nil? || dependencies.empty?
+      available.delete(flag_key)
+      return [flag]
+    end
+
+    path.add(flag_key)
+    result = []
+    dependencies.each do |parent_key|
+      raise CycleError, path if path.include?(parent_key)
+
+      traversal = parent_traversal(parent_key, available, path)
+      result.concat(traversal) unless traversal.nil?
+    end
+    result << flag
+    path.delete(flag_key)
+    available.delete(flag_key)
+    result
+  end
+end

data/lib/experiment/util/user.rb

@@ -0,0 +1,41 @@
+module AmplitudeExperiment
+  def self.user_to_evaluation_context(user)
+    user_groups = user.groups
+    user_group_properties = user.group_properties
+    user_group_cohort_ids = user.group_cohort_ids
+    user_hash = user.as_json.compact
+    user_hash.delete('groups')
+    user_hash.delete('group_properties')
+    user_hash.delete('group_cohort_ids')
+
+    context = user_hash.empty? ? {} : { 'user' => user_hash }
+
+    return context if user_groups.nil?
+
+    groups = {}
+    user_groups.each do |group_type, group_name|
+      group_name = group_name[0] if group_name.is_a?(Array) && !group_name.empty?
+
+      groups[group_type] = { 'group_name' => group_name }
+
+      if user_group_properties
+        group_properties_type = user_group_properties[group_type]
+        if group_properties_type.is_a?(Hash)
+          group_properties_name = group_properties_type[group_name]
+          groups[group_type]['group_properties'] = group_properties_name if group_properties_name.is_a?(Hash)
+        end
+      end
+
+      next unless user_group_cohort_ids
+
+      group_cohort_ids_type = user_group_cohort_ids[group_type]
+      if group_cohort_ids_type.is_a?(Hash)
+        group_cohort_ids_name = group_cohort_ids_type[group_name]
+        groups[group_type]['cohort_ids'] = group_cohort_ids_name if group_cohort_ids_name.is_a?(Array)
+      end
+    end
+
+    context['groups'] = groups unless groups.empty?
+    context
+  end
+end

data/lib/experiment/util/variant.rb

@@ -0,0 +1,32 @@
+require 'json'
+module AmplitudeExperiment
+  def self.evaluation_variants_json_to_variants(variants_json)
+    variants = {}
+    variants_json.each do |key, value|
+      variants[key] = AmplitudeExperiment.evaluation_variant_json_to_variant(value)
+    end
+    variants
+  end
+
+  def self.evaluation_variant_json_to_variant(variant_json)
+    value = variant_json['value']
+    value = value.to_json if value && !value.is_a?(String)
+    Variant.new(
+      value: value,
+      key: variant_json['key'],
+      payload: variant_json['payload'],
+      metadata: variant_json['metadata']
+    )
+  end
+
+  def self.filter_default_variants(variants)
+    variants.each do |key, value|
+      default = value&.metadata&.fetch('default', nil)
+      deployed = value&.metadata&.fetch('deployed', nil)
+      default = false if default.nil?
+      deployed = true if deployed.nil?
+      variants.delete(key) if default || !deployed
+    end
+    variants
+  end
+end