amplitude-experiment 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6df1a01ac720c72256be526321f9b30f93fcdde050ff6a0743c24bd53a64dd5b
-  data.tar.gz: d10ebba30ae8a59b7964536909315059c8d096dc1b3a9d0e735c7242db400153
+  metadata.gz: c79062c9e6a6f0877449f49dab03aa2445cf31700ecb92010f88d5779759d73a
+  data.tar.gz: 1cf7d73b53cb125ecfaa6987bb4569d7416c5b02e194ef9f90be65c8da0b2fe6
 SHA512:
-  metadata.gz: d623457be0fb4cc632f708365d53abbab2b7b647baf7ab37d18d6a05f21e321960e0632152ff2e60686d590e598cfa4333313cb6e31ad29868d2e4798be3e200
-  data.tar.gz: e9800dd0da6e0edf6ee8c01bf289700e7f61963fc2e379ea55ddd54dda7c52c8b85f0185c07fcd2a3d2aa8b92391a0bda9828c794f1960d16e39f1e10ed15210
+  metadata.gz: 45e8a5540fc7a0e9a9213bdfe7c8828137d35aee0ab6d5dab50e79cac47bf858f11db626a545f131c7a5e48bf05b04b9b82944441d5c307d9562fd42973e5edb
+  data.tar.gz: ffebca0974025ed2e983b106468be3806eb724cb5f0a2723d0f2782b67005d679ca8cfec4edb1b5236578a855472838a1f20e81d7641e362301d35fc5bfec32c

data/amplitude-experiment.gemspec

@@ -24,10 +24,11 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rdoc', '= 6.4'
   spec.add_development_dependency 'rspec', '~> 3.6'
-  spec.add_development_dependency 'rubocop', '= 1.21'
+  spec.add_development_dependency 'rubocop', '= 1.22.3'
   spec.add_development_dependency 'simplecov', '~> 0.21'
   spec.add_development_dependency 'webmock', '~> 3.14'
   spec.add_development_dependency 'yard', '~> 0.9'
+  spec.add_development_dependency 'dotenv', '~> 2.8.1'
   spec.metadata['rubygems_mfa_required'] = 'false'
   spec.add_runtime_dependency 'ffi', '~> 1.15'
 end

data/lib/amplitude-experiment.rb

@@ -8,7 +8,6 @@ require 'experiment/factory'
 require 'experiment/remote/client'
 require 'experiment/local/client'
 require 'experiment/local/config'
-require 'experiment/local/fetcher'
 require 'experiment/local/assignment/assignment'
 require 'experiment/local/assignment/assignment_filter'
 require 'experiment/local/assignment/assignment_service'
@@ -19,6 +18,16 @@ require 'experiment/util/topological_sort'
 require 'experiment/util/user'
 require 'experiment/util/variant'
 require 'experiment/error'
+require 'experiment/util/flag_config'
+require 'experiment/flag/flag_config_fetcher'
+require 'experiment/flag/flag_config_storage'
+require 'experiment/cohort/cohort_download_api'
+require 'experiment/cohort/cohort'
+require 'experiment/cohort/cohort_loader'
+require 'experiment/cohort/cohort_storage'
+require 'experiment/cohort/cohort_sync_config'
+require 'experiment/deployment/deployment_runner'
+require 'experiment/util/poller'
 
 # Amplitude Experiment Module
 module AmplitudeExperiment

data/lib/experiment/cohort/cohort.rb

@@ -0,0 +1,25 @@
+module AmplitudeExperiment
+  USER_GROUP_TYPE = 'User'.freeze
+  # Cohort
+  class Cohort
+    attr_accessor :id, :last_modified, :size, :member_ids, :group_type
+
+    def initialize(id, last_modified, size, member_ids, group_type = USER_GROUP_TYPE)
+      @id = id
+      @last_modified = last_modified
+      @size = size
+      @member_ids = member_ids.to_set
+      @group_type = group_type
+    end
+
+    def ==(other)
+      return false unless other.is_a?(Cohort)
+
+      @id == other.id &&
+        @last_modified == other.last_modified &&
+        @size == other.size &&
+        @member_ids == other.member_ids &&
+        @group_type == other.group_type
+    end
+  end
+end

data/lib/experiment/cohort/cohort_download_api.rb

@@ -0,0 +1,90 @@
+require 'base64'
+require 'json'
+require 'net/http'
+require 'uri'
+require 'set'
+
+module AmplitudeExperiment
+  # CohortDownloadApi
+  class CohortDownloadApi
+    COHORT_REQUEST_TIMEOUT_MILLIS = 5000
+    COHORT_REQUEST_RETRY_DELAY_MILLIS = 100
+
+    def get_cohort(cohort_id, cohort = nil)
+      raise NotImplementedError
+    end
+  end
+
+  # DirectCohortDownloadApi
+  class DirectCohortDownloadApi < CohortDownloadApi
+    def initialize(api_key, secret_key, max_cohort_size, server_url, logger)
+      super()
+      @api_key = api_key
+      @secret_key = secret_key
+      @max_cohort_size = max_cohort_size
+      @server_url = server_url
+      @logger = logger
+    end
+
+    def get_cohort(cohort_id, cohort = nil)
+      @logger.debug("getCohortMembers(#{cohort_id}): start")
+      errors = 0
+
+      loop do
+        begin
+          last_modified = cohort.nil? ? nil : cohort.last_modified
+          response = get_cohort_members_request(cohort_id, last_modified)
+          @logger.debug("getCohortMembers(#{cohort_id}): status=#{response.code}")
+
+          case response.code.to_i
+          when 200
+            cohort_info = JSON.parse(response.body)
+            @logger.debug("getCohortMembers(#{cohort_id}): end - resultSize=#{cohort_info['size']}")
+            return Cohort.new(
+              cohort_info['cohortId'],
+              cohort_info['lastModified'],
+              cohort_info['size'],
+              cohort_info['memberIds'].to_set,
+              cohort_info['groupType']
+            )
+          when 204
+            @logger.debug("getCohortMembers(#{cohort_id}): Cohort not modified")
+            return nil
+          when 413
+            raise CohortTooLargeError.new(cohort_id, "Cohort exceeds max cohort size: #{response.code}")
+          else
+            raise HTTPErrorResponseError.new(response.code, cohort_id, "Unexpected response code: #{response.code}") if response.code.to_i != 202
+
+          end
+        rescue StandardError => e
+          errors += 1 unless response && e.is_a?(HTTPErrorResponseError) && response.code.to_i == 429
+          @logger.debug("getCohortMembers(#{cohort_id}): request-status error #{errors} - #{e}")
+          raise e if errors >= 3 || e.is_a?(CohortTooLargeError)
+        end
+
+        sleep(COHORT_REQUEST_RETRY_DELAY_MILLIS / 1000.0)
+      end
+    end
+
+    private
+
+    def get_cohort_members_request(cohort_id, last_modified)
+      headers = {
+        'Authorization' => "Basic #{basic_auth}",
+        'Content-Type' => 'application/json;charset=utf-8',
+        'X-Amp-Exp-Library' => "experiment-ruby-server/#{VERSION}"
+      }
+      url = "#{@server_url}/sdk/v1/cohort/#{cohort_id}?maxCohortSize=#{@max_cohort_size}"
+      url += "&lastModified=#{last_modified}" if last_modified
+
+      request = Net::HTTP::Get.new(URI(url), headers)
+      http = PersistentHttpClient.get(@server_url, { read_timeout: COHORT_REQUEST_TIMEOUT_MILLIS }, basic_auth)
+      http.request(request)
+    end
+
+    def basic_auth
+      credentials = "#{@api_key}:#{@secret_key}"
+      Base64.strict_encode64(credentials)
+    end
+  end
+end

data/lib/experiment/cohort/cohort_loader.rb

@@ -0,0 +1,39 @@
+module AmplitudeExperiment
+  # CohortLoader
+  class CohortLoader
+    def initialize(cohort_download_api, cohort_storage)
+      @cohort_download_api = cohort_download_api
+      @cohort_storage = cohort_storage
+      @jobs = {}
+      @lock_jobs = Mutex.new
+    end
+
+    def load_cohort(cohort_id)
+      @lock_jobs.synchronize do
+        unless @jobs.key?(cohort_id)
+          future = Concurrent::Promises.future do
+            load_cohort_internal(cohort_id)
+          ensure
+            remove_job(cohort_id)
+          end
+          @jobs[cohort_id] = future
+        end
+        @jobs[cohort_id]
+      end
+    end
+
+    private
+
+    def load_cohort_internal(cohort_id)
+      stored_cohort = @cohort_storage.cohort(cohort_id)
+      updated_cohort = @cohort_download_api.get_cohort(cohort_id, stored_cohort)
+      @cohort_storage.put_cohort(updated_cohort) unless updated_cohort.nil?
+    end
+
+    def remove_job(cohort_id)
+      @lock_jobs.synchronize do
+        @jobs.delete(cohort_id)
+      end
+    end
+  end
+end

data/lib/experiment/cohort/cohort_storage.rb

@@ -0,0 +1,91 @@
+module AmplitudeExperiment
+  # CohortStorage
+  class CohortStorage
+    def cohort(cohort_id)
+      raise NotImplementedError
+    end
+
+    def cohorts
+      raise NotImplementedError
+    end
+
+    def get_cohorts_for_user(user_id, cohort_ids)
+      raise NotImplementedError
+    end
+
+    def get_cohorts_for_group(group_type, group_name, cohort_ids)
+      raise NotImplementedError
+    end
+
+    def put_cohort(cohort_description)
+      raise NotImplementedError
+    end
+
+    def delete_cohort(group_type, cohort_id)
+      raise NotImplementedError
+    end
+
+    def cohort_ids
+      raise NotImplementedError
+    end
+  end
+
+  class InMemoryCohortStorage < CohortStorage
+    def initialize
+      super
+      @lock = Mutex.new
+      @group_to_cohort_store = {}
+      @cohort_store = {}
+    end
+
+    def cohort(cohort_id)
+      @lock.synchronize do
+        @cohort_store[cohort_id]
+      end
+    end
+
+    def cohorts
+      @lock.synchronize do
+        @cohort_store.dup
+      end
+    end
+
+    def get_cohorts_for_user(user_id, cohort_ids)
+      get_cohorts_for_group(USER_GROUP_TYPE, user_id, cohort_ids)
+    end
+
+    def get_cohorts_for_group(group_type, group_name, cohort_ids)
+      result = Set.new
+      @lock.synchronize do
+        group_type_cohorts = @group_to_cohort_store[group_type] || Set.new
+        group_type_cohorts.each do |cohort_id|
+          members = @cohort_store[cohort_id]&.member_ids || Set.new
+          result.add(cohort_id) if cohort_ids.include?(cohort_id) && members.include?(group_name)
+        end
+      end
+      result
+    end
+
+    def put_cohort(cohort)
+      @lock.synchronize do
+        @group_to_cohort_store[cohort.group_type] ||= Set.new
+        @group_to_cohort_store[cohort.group_type].add(cohort.id)
+        @cohort_store[cohort.id] = cohort
+      end
+    end
+
+    def delete_cohort(group_type, cohort_id)
+      @lock.synchronize do
+        group_cohorts = @group_to_cohort_store[group_type] || Set.new
+        group_cohorts.delete(cohort_id)
+        @cohort_store.delete(cohort_id)
+      end
+    end
+
+    def cohort_ids
+      @lock.synchronize do
+        @cohort_store.keys.to_set
+      end
+    end
+  end
+end

data/lib/experiment/cohort/cohort_sync_config.rb

@@ -0,0 +1,27 @@
+module AmplitudeExperiment
+  DEFAULT_COHORT_SYNC_URL = 'https://cohort-v2.lab.amplitude.com'.freeze
+  EU_COHORT_SYNC_URL = 'https://cohort-v2.lab.eu.amplitude.com'.freeze
+
+  # Experiment Cohort Sync Configuration
+  class CohortSyncConfig
+    # This configuration is used to set up the cohort loader. The cohort loader is responsible for
+    # downloading cohorts from the server and storing them locally.
+    #   Parameters:
+    #     api_key (str): The project API Key
+    #     secret_key (str): The project Secret Key
+    #     max_cohort_size (int): The maximum cohort size that can be downloaded
+    #     cohort_polling_interval_millis (int): The interval in milliseconds to poll for cohorts, the minimum value is 60000
+    #     cohort_server_url (str): The server endpoint from which to request cohorts
+
+    attr_accessor :api_key, :secret_key, :max_cohort_size, :cohort_polling_interval_millis, :cohort_server_url
+
+    def initialize(api_key, secret_key, max_cohort_size: 2_147_483_647, cohort_polling_interval_millis: 60_000,
+                   cohort_server_url: DEFAULT_COHORT_SYNC_URL)
+      @api_key = api_key
+      @secret_key = secret_key
+      @max_cohort_size = max_cohort_size
+      @cohort_polling_interval_millis = [cohort_polling_interval_millis, 60_000].max
+      @cohort_server_url = cohort_server_url
+    end
+  end
+end

data/lib/experiment/deployment/deployment_runner.rb

@@ -0,0 +1,135 @@
+require 'set'
+
+module AmplitudeExperiment
+  # DeploymentRunner
+  class DeploymentRunner
+    def initialize(
+      config,
+      flag_config_fetcher,
+      flag_config_storage,
+      cohort_storage,
+      logger,
+      cohort_loader = nil
+    )
+      @config = config
+      @flag_config_fetcher = flag_config_fetcher
+      @flag_config_storage = flag_config_storage
+      @cohort_storage = cohort_storage
+      @cohort_loader = cohort_loader
+      @lock = Mutex.new
+      @logger = logger
+      @executor = Concurrent::ThreadPoolExecutor.new(
+        max_threads: 10,
+        name: 'DeploymentRunnerExecutor'
+      )
+    end
+
+    def start
+      @lock.synchronize do
+        update_flag_configs
+        @flag_poller = Poller.new(
+          @config.flag_config_polling_interval_millis / 1000.0,
+          method(:periodic_flag_update)
+        )
+        @flag_poller.start
+        if @config.cohort_sync_config
+          @cohort_poller = Poller.new(
+            @config.cohort_sync_config.cohort_polling_interval_millis / 1000.0,
+            method(:update_cohorts)
+          )
+          @cohort_poller.start
+        end
+      end
+    end
+
+    def stop
+      @flag_poller&.stop
+      @flag_poller = nil
+      @cohort_poller&.stop
+      @cohort_poller = nil
+    end
+
+    private
+
+    def periodic_flag_update
+      @logger.debug('Periodic flag update: start')
+      update_flag_configs
+    rescue StandardError => e
+      @logger.error("Error while updating flags: #{e}")
+    end
+
+    def update_flag_configs
+      flags = @flag_config_fetcher.fetch_v2
+      flag_configs = flags.each_with_object({}) { |flag, hash| hash[flag['key']] = flag }
+      flag_keys = flag_configs.values.map { |flag| flag['key'] }.to_set
+      @flag_config_storage.remove_if { |f| !flag_keys.include?(f['key']) }
+
+      unless @cohort_loader
+        flag_configs.each do |flag_key, flag_config|
+          @logger.debug("Putting non-cohort flag #{flag_key}")
+          @flag_config_storage.put_flag_config(flag_config)
+        end
+        return
+      end
+
+      new_cohort_ids = Set.new
+      flag_configs.each do |_, flag_config|
+        new_cohort_ids.merge(AmplitudeExperiment.get_all_cohort_ids_from_flag(flag_config))
+      end
+
+      existing_cohort_ids = @cohort_storage.cohort_ids
+      cohort_ids_to_download = new_cohort_ids - existing_cohort_ids
+
+      download_cohorts(cohort_ids_to_download)
+
+      updated_cohort_ids = @cohort_storage.cohort_ids
+
+      flag_configs.each do |flag_key, flag_config|
+        cohort_ids = AmplitudeExperiment.get_all_cohort_ids_from_flag(flag_config)
+        @logger.debug("Storing flag #{flag_key}")
+        @flag_config_storage.put_flag_config(flag_config)
+        missing_cohorts = cohort_ids - updated_cohort_ids
+
+        @logger.warn("Flag #{flag_key} - failed to load cohorts: #{missing_cohorts}") if missing_cohorts.any?
+      end
+
+      delete_unused_cohorts
+      @logger.debug("Refreshed #{flag_configs.size} flag configs.")
+    end
+
+    def download_cohorts(cohort_ids)
+      futures = cohort_ids.map do |cohort_id|
+        Concurrent::Promises.future_on(@executor) do
+          future = @cohort_loader.load_cohort(cohort_id)
+          future.value!
+        rescue StandardError => e
+          @logger.error("Failed to download cohort #{cohort_id}: #{e.message}")
+          nil
+        end
+      end
+
+      Concurrent::Promises.zip(*futures).value!
+    end
+
+    def update_cohorts
+      @logger.debug('Periodic cohort update: start')
+      cohort_ids = AmplitudeExperiment.get_all_cohort_ids_from_flags(@flag_config_storage.flag_configs)
+      download_cohorts(cohort_ids)
+    end
+
+    def delete_unused_cohorts
+      flag_cohort_ids = Set.new
+      @flag_config_storage.flag_configs.each do |_, flag|
+        flag_cohort_ids.merge(AmplitudeExperiment.get_all_cohort_ids_from_flag(flag))
+      end
+
+      storage_cohorts = @cohort_storage.cohorts
+      deleted_cohort_ids = storage_cohorts.keys.to_set - flag_cohort_ids
+
+      deleted_cohort_ids.each do |deleted_cohort_id|
+        deleted_cohort = storage_cohorts[deleted_cohort_id]
+        @cohort_storage.delete_cohort(deleted_cohort.group_type, deleted_cohort_id) if deleted_cohort
+      end
+    end
+  end
+end

data/lib/experiment/error.rb

@@ -9,6 +9,29 @@ module AmplitudeExperiment
     end
   end
 
+  class CohortDownloadError < StandardError
+    attr_reader :cohort_id
+
+    def initialize(cohort_id, message)
+      super(message)
+      @cohort_id = cohort_id
+    end
+  end
+
+  # CohortTooLargeError
+  class CohortTooLargeError < CohortDownloadError
+  end
+
+  # HTTPErrorResponseError
+  class HTTPErrorResponseError < CohortDownloadError
+    attr_reader :status_code
+
+    def initialize(status_code, cohort_id, message)
+      super(cohort_id, message)
+      @status_code = status_code
+    end
+  end
+
   class CycleError < StandardError
     # Raised when topological sorting encounters a cycle between flag dependencies.
     attr_reader :path

data/lib/experiment/{local/fetcher.rb → flag/flag_config_fetcher.rb}

@@ -9,7 +9,6 @@ module AmplitudeExperiment
       @api_key = api_key
       @server_url = server_url
       @logger = logger
-      @http = PersistentHttpClient.get(server_url, { read_timeout: FLAG_CONFIG_TIMEOUT }, @api_key)
     end
 
     # Fetch local evaluation mode flag configs from the Experiment API server.
@@ -24,7 +23,8 @@ module AmplitudeExperiment
         'X-Amp-Exp-Library' => "experiment-ruby-server/#{VERSION}"
       }
       request = Net::HTTP::Get.new("#{@server_url}/sdk/v1/flags", headers)
-      response = @http.request(request)
+      http = PersistentHttpClient.get(@server_url, { read_timeout: FLAG_CONFIG_TIMEOUT }, @api_key)
+      response = http.request(request)
       raise "flagConfigs - received error response: #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPOK)
 
       @logger.debug("[Experiment] Fetch flag configs: #{response.body}")
@@ -39,11 +39,12 @@ module AmplitudeExperiment
         'X-Amp-Exp-Library' => "experiment-ruby-server/#{VERSION}"
       }
       request = Net::HTTP::Get.new("#{@server_url}/sdk/v2/flags?v=0", headers)
-      response = @http.request(request)
+      http = PersistentHttpClient.get(@server_url, { read_timeout: FLAG_CONFIG_TIMEOUT }, @api_key)
+      response = http.request(request)
       raise "flagConfigs - received error response: #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPOK)
 
       @logger.debug("[Experiment] Fetch flag configs: #{response.body}")
-      response.body
+      JSON.parse(response.body)
     end
 
     # Fetch local evaluation mode flag configs from the Experiment API server.
@@ -58,7 +59,8 @@ module AmplitudeExperiment
         'X-Amp-Exp-Library' => "experiment-ruby-server/#{VERSION}"
       }
       request = Net::HTTP::Get.new("#{@server_url}/sdk/rules?eval_mode=local", headers)
-      response = @http.request(request)
+      http = PersistentHttpClient.get(@server_url, { read_timeout: FLAG_CONFIG_TIMEOUT }, @api_key)
+      response = http.request(request)
       raise "flagConfigs - received error response: #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPOK)
 
       flag_configs = parse(response.body)

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

@@ -23,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.
@@ -51,19 +64,18 @@ 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)
+      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
 
-      enriched_user = AmplitudeExperiment.user_to_evaluation_context(user)
-      user_str = enriched_user.to_json
-
-      @logger.debug("[Experiment] Evaluate: User: #{user_str} - Rules: #{flags}") if @config.debug
-      result = evaluation(flags_json, 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
       variants = AmplitudeExperiment.evaluation_variants_json_to_variants(result)
       @assignment_service&.track(Assignment.new(user, variants))
@@ -76,34 +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 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/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.5.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: amplitude-experiment
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Amplitude
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-07-29 00:00:00.000000000 Z
+date: 2024-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: '1.21'
+        version: 1.22.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: '1.21'
+        version: 1.22.3
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -136,6 +136,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.8.1
 - !ruby/object:Gem::Dependency
   name: ffi
   requirement: !ruby/object:Gem::Requirement
@@ -175,9 +189,17 @@ files:
 - lib/amplitude/timeline.rb
 - lib/amplitude/utils.rb
 - lib/amplitude/workers.rb
+- lib/experiment/cohort/cohort.rb
+- lib/experiment/cohort/cohort_download_api.rb
+- lib/experiment/cohort/cohort_loader.rb
+- lib/experiment/cohort/cohort_storage.rb
+- lib/experiment/cohort/cohort_sync_config.rb
 - lib/experiment/cookie.rb
+- lib/experiment/deployment/deployment_runner.rb
 - lib/experiment/error.rb
 - lib/experiment/factory.rb
+- lib/experiment/flag/flag_config_fetcher.rb
+- lib/experiment/flag/flag_config_storage.rb
 - lib/experiment/local/assignment/assignment.rb
 - lib/experiment/local/assignment/assignment_config.rb
 - lib/experiment/local/assignment/assignment_filter.rb
@@ -193,13 +215,14 @@ files:
 - lib/experiment/local/evaluation/lib/macosArm64/libevaluation_interop_api.h
 - lib/experiment/local/evaluation/lib/macosX64/libevaluation_interop.dylib
 - lib/experiment/local/evaluation/lib/macosX64/libevaluation_interop_api.h
-- lib/experiment/local/fetcher.rb
 - lib/experiment/persistent_http_client.rb
 - lib/experiment/remote/client.rb
 - lib/experiment/remote/config.rb
 - lib/experiment/user.rb
+- lib/experiment/util/flag_config.rb
 - lib/experiment/util/hash.rb
 - lib/experiment/util/lru_cache.rb
+- lib/experiment/util/poller.rb
 - lib/experiment/util/topological_sort.rb
 - lib/experiment/util/user.rb
 - lib/experiment/util/variant.rb