amplitude-experiment 1.4.0 → 1.6.0

data/lib/experiment/flag/flag_config_storage.rb

@@ -0,0 +1,53 @@
+module AmplitudeExperiment
+  # FlagConfigStorage
+  class FlagConfigStorage
+    def flag_config(key)
+      raise NotImplementedError
+    end
+
+    def flag_configs
+      raise NotImplementedError
+    end
+
+    def put_flag_config(flag_config)
+      raise NotImplementedError
+    end
+
+    def remove_if(&condition)
+      raise NotImplementedError
+    end
+  end
+
+  # InMemoryFlagConfigStorage
+  class InMemoryFlagConfigStorage < FlagConfigStorage
+    def initialize
+      super # Call the parent class's constructor with no arguments
+      @flag_configs = {}
+      @flag_configs_lock = Mutex.new
+    end
+
+    def flag_config(key)
+      @flag_configs_lock.synchronize do
+        @flag_configs[key]
+      end
+    end
+
+    def flag_configs
+      @flag_configs_lock.synchronize do
+        @flag_configs.dup
+      end
+    end
+
+    def put_flag_config(flag_config)
+      @flag_configs_lock.synchronize do
+        @flag_configs[flag_config.key] = flag_config
+      end
+    end
+
+    def remove_if
+      @flag_configs_lock.synchronize do
+        @flag_configs.delete_if { |_key, value| yield(value) }
+      end
+    end
+  end
+end

data/lib/experiment/local/client.rb

@@ -12,7 +12,6 @@ module AmplitudeExperiment
     # @param [LocalEvaluationConfig] config The config object
 
     def initialize(api_key, config = nil)
-      require 'experiment/local/evaluation/evaluation'
       @api_key = api_key
       @config = config || LocalEvaluationConfig.new
       @flags = nil
@@ -23,11 +22,26 @@ 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?
 
+      @engine = Evaluation::Engine.new
+
       @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.
@@ -51,19 +65,16 @@ module AmplitudeExperiment
     # @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 = @flags_mutex.synchronize do
-        @flags
-      end
+      flags = @flag_config_storage.flag_configs
       return {} if flags.nil?
 
-      sorted_flags = AmplitudeExperiment.topological_sort(flags, flag_keys.to_set)
-      flags_json = sorted_flags.to_json
-
-      enriched_user = AmplitudeExperiment.user_to_evaluation_context(user)
-      user_str = enriched_user.to_json
+      sorted_flags = TopologicalSort.sort(flags, flag_keys)
+      required_cohorts_in_storage(sorted_flags)
+      user = enrich_user_with_cohorts(user, flags) if @config.cohort_sync_config
+      context = AmplitudeExperiment.user_to_evaluation_context(user)
 
-      @logger.debug("[Experiment] Evaluate: User: #{user_str} - Rules: #{flags}") if @config.debug
-      result = evaluation(flags_json, user_str)
+      @logger.debug("[Experiment] Evaluate: User: #{context} - Rules: #{flags}") if @config.debug
+      result = @engine.evaluate(context, sorted_flags)
       @logger.debug("[Experiment] evaluate - result: #{result}") if @config.debug
       variants = AmplitudeExperiment.evaluation_variants_json_to_variants(result)
       @assignment_service&.track(Assignment.new(user, variants))
@@ -76,34 +87,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 run
-      @is_running = true
-      begin
-        flags = @fetcher.fetch_v2
-        flags_obj = JSON.parse(flags)
-        flags_map = flags_obj.each_with_object({}) { |flag, hash| hash[flag['key']] = flag }
-        @flags_mutex.synchronize do
-          @flags = flags_map
-        end
-      rescue StandardError => e
-        @logger.error("[Experiment] Flag poller - error: #{e.message}")
+    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
+    end
+
+    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/persistent_http_client.rb

@@ -5,7 +5,7 @@ module AmplitudeExperiment
   # WARNING: these connections are not safe for concurrent requests. Callers
   # must synchronize requests per connection.
   class PersistentHttpClient
-    DEFAULT_OPTIONS = { read_timeout: 80 }.freeze
+    DEFAULT_OPTIONS = { open_timeout: 60, read_timeout: 80 }.freeze
 
     class << self
       # url: URI / String

data/lib/experiment/remote/client.rb

@@ -89,7 +89,7 @@ module AmplitudeExperiment
     # @param [User] user
     def fetch_internal(user)
       @logger.debug("[Experiment] Fetching variants for user: #{user.as_json}")
-      do_fetch(user, @config.fetch_timeout_millis)
+      do_fetch(user, @config.connect_timeout_millis, @config.fetch_timeout_millis)
     rescue StandardError => e
       @logger.error("[Experiment] Fetch failed: #{e.message}")
       if should_retry_fetch?(e)
@@ -112,7 +112,7 @@ module AmplitudeExperiment
       @config.fetch_retries.times do
         sleep(delay_millis.to_f / 1000.0)
         begin
-          return do_fetch(user, @config.fetch_retry_timeout_millis)
+          return do_fetch(user, @config.connect_timeout_millis, @config.fetch_retry_timeout_millis)
         rescue StandardError => e
           @logger.error("[Experiment] Retry failed: #{e.message}")
           err = e
@@ -123,16 +123,18 @@ module AmplitudeExperiment
     end
 
     # @param [User] user
-    # @param [Integer] timeout_millis
-    def do_fetch(user, timeout_millis)
+    # @param [Integer] connect_timeout_millis
+    # @param [Integer] fetch_timeout_millis
+    def do_fetch(user, connect_timeout_millis, fetch_timeout_millis)
       start_time = Time.now
       user_context = add_context(user)
       headers = {
         'Authorization' => "Api-Key #{@api_key}",
         'Content-Type' => 'application/json;charset=utf-8'
       }
-      read_timeout = timeout_millis.to_f / 1000 if (timeout_millis.to_f / 1000) > 0
-      http = PersistentHttpClient.get(@uri, { read_timeout: read_timeout }, @api_key)
+      connect_timeout = connect_timeout_millis.to_f / 1000 if (connect_timeout_millis.to_f / 1000) > 0
+      read_timeout = fetch_timeout_millis.to_f / 1000 if (fetch_timeout_millis.to_f / 1000) > 0
+      http = PersistentHttpClient.get(@uri, { open_timeout: connect_timeout, read_timeout: read_timeout }, @api_key)
       request = Net::HTTP::Post.new(@uri, headers)
       request.body = user_context.to_json
       @logger.warn("[Experiment] encoded user object length #{request.body.length} cannot be cached by CDN; must be < 8KB") if request.body.length > 8000

data/lib/experiment/remote/config.rb

@@ -12,6 +12,10 @@ module AmplitudeExperiment
     # @return [Boolean] the value of server url
     attr_accessor :server_url
 
+    # The request connection open timeout, in milliseconds, used when fetching variants triggered by calling start() or setUser().
+    # @return [Integer] the value of connect_timeout_millis
+    attr_accessor :connect_timeout_millis
+
     # The request timeout, in milliseconds, used when fetching variants triggered by calling start() or setUser().
     # @return [Integer] the value of fetch_timeout_millis
     attr_accessor :fetch_timeout_millis
@@ -40,6 +44,8 @@ module AmplitudeExperiment
 
     # @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 [Integer] connect_timeout_millis The request connection open timeout, in milliseconds, used when
+    #  fetching variants triggered by calling start() or setUser().
     # @param [Integer] fetch_timeout_millis The request timeout, in milliseconds, used when fetching variants
     #  triggered by calling start() or setUser().
     # @param [Integer] fetch_retries The number of retries to attempt before failing.
@@ -49,11 +55,12 @@ module AmplitudeExperiment
     #  greater than the max, the max is used for all subsequent retries.
     # @param [Float] fetch_retry_backoff_scalar Scales the minimum backoff exponentially.
     # @param [Integer] fetch_retry_timeout_millis The request timeout for retrying fetch requests.
-    def initialize(debug: false, server_url: DEFAULT_SERVER_URL, fetch_timeout_millis: 10_000, fetch_retries: 0,
+    def initialize(debug: false, server_url: DEFAULT_SERVER_URL, connect_timeout_millis: 60_000, fetch_timeout_millis: 10_000, fetch_retries: 0,
                    fetch_retry_backoff_min_millis: 500, fetch_retry_backoff_max_millis: 10_000,
                    fetch_retry_backoff_scalar: 1.5, fetch_retry_timeout_millis: 10_000)
       @debug = debug
       @server_url = server_url
+      @connect_timeout_millis = connect_timeout_millis
       @fetch_timeout_millis = fetch_timeout_millis
       @fetch_retries = fetch_retries
       @fetch_retry_backoff_min_millis = fetch_retry_backoff_min_millis

data/lib/experiment/user.rb

@@ -80,6 +80,14 @@ module AmplitudeExperiment
     # @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
@@ -101,7 +109,8 @@ module AmplitudeExperiment
     # @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, groups: nil, group_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
@@ -121,31 +130,35 @@ module AmplitudeExperiment
       @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,
-        groups: @groups,
-        group_properties: @group_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
 
@@ -154,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/user.rb

@@ -2,11 +2,13 @@ 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('groups')
+    user_hash.delete('group_properties')
+    user_hash.delete('group_cohort_ids')
 
-    context = user_hash.empty? ? {} : { user: user_hash }
+    context = user_hash.empty? ? {} : { 'user' => user_hash }
 
     return context if user_groups.nil?
 
@@ -14,20 +16,26 @@ module AmplitudeExperiment
     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.to_sym] = { group_name: group_name }
+      groups[group_type] = { 'group_name' => group_name }
 
-      next if user_group_properties.nil?
+      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
 
-      group_properties_type = user_group_properties[group_type.to_sym]
-      next if group_properties_type.nil? || !group_properties_type.is_a?(Hash)
+      next unless user_group_cohort_ids
 
-      group_properties_name = group_properties_type[group_name.to_sym]
-      next if group_properties_name.nil? || !group_properties_name.is_a?(Hash)
-
-      groups[group_type.to_sym][:group_properties] = group_properties_name
+      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['groups'] = groups unless groups.empty?
     context
   end
 end

data/lib/experiment/version.rb

@@ -1,3 +1,3 @@
 module AmplitudeExperiment
-  VERSION = '1.4.0'.freeze
+  VERSION = '1.6.0'.freeze
 end