amplitude-experiment 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6df1a01ac720c72256be526321f9b30f93fcdde050ff6a0743c24bd53a64dd5b
-  data.tar.gz: d10ebba30ae8a59b7964536909315059c8d096dc1b3a9d0e735c7242db400153
+  metadata.gz: 6d05f9400e7dd25e87eb6f372c0c1c7fa5c083fe392a75dd25152e0ad0c010a1
+  data.tar.gz: 19df424d3a56c5a44d6495282f3e1f5022e1a50c47b4a5e0fcfc53c0535576ea
 SHA512:
-  metadata.gz: d623457be0fb4cc632f708365d53abbab2b7b647baf7ab37d18d6a05f21e321960e0632152ff2e60686d590e598cfa4333313cb6e31ad29868d2e4798be3e200
-  data.tar.gz: e9800dd0da6e0edf6ee8c01bf289700e7f61963fc2e379ea55ddd54dda7c52c8b85f0185c07fcd2a3d2aa8b92391a0bda9828c794f1960d16e39f1e10ed15210
+  metadata.gz: 4e2e412e261f918990f23890200e9dc7b2cf0ed5b52e38fe585f10a3bd84f3b2d062c21a60dbf6811fdf27c395635f214f433d5dfb77c5573e3ae7e82a803352
+  data.tar.gz: 3bde003e6e5cb0d8b139218d408c5235949bed823f6973fb3f45f3eb542d7adfc7cdfe74f416bf62f06d6cd910eace6490bb6e4e3e6a0b7ef8f4abe686c854b4

data/amplitude-experiment.gemspec

@@ -14,20 +14,21 @@ Gem::Specification.new do |spec|
   spec.files                 = Dir['README.md',
                                    'lib/**/*.rb',
                                    'amplitude-experiment.gemspec',
-                                   'Gemfile',
-                                   'lib/experiment/local/evaluation/lib/**/*']
+                                   'Gemfile']
   spec.require_paths         = ['lib']
   spec.extra_rdoc_files      = ['README.md']
 
-  spec.add_development_dependency 'concurrent-ruby', '~> 1.2.2'
+  spec.add_dependency 'concurrent-ruby', '~> 1.2.2'
+
   spec.add_development_dependency 'psych', '~> 4.0'
   spec.add_development_dependency 'rake', '~> 13.0'
-  spec.add_development_dependency 'rdoc', '= 6.4'
+  spec.add_development_dependency 'rdoc', '= 6.10'
   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.add_development_dependency 'jar-dependencies', '= 0.4.1'
   spec.metadata['rubygems_mfa_required'] = 'false'
-  spec.add_runtime_dependency 'ffi', '~> 1.15'
 end

data/lib/amplitude-experiment.rb

@@ -8,17 +8,31 @@ 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'
 require 'experiment/local/assignment/assignment_config'
 require 'experiment/util/lru_cache'
 require 'experiment/util/hash'
-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'
+require 'experiment/evaluation/evaluation'
+require 'experiment/evaluation/flag'
+require 'experiment/evaluation/murmur3'
+require 'experiment/evaluation/select'
+require 'experiment/evaluation/semantic_version'
+require 'experiment/evaluation/topological_sort'
 
 # 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.map { |f| [f.key, f] }.to_h
+      flag_keys = flag_configs.keys.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