amplitude-experiment 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 021a7dbe3ce531b888b2df293019ad43c0f492e4662e6fc211694e06a321253b
-  data.tar.gz: 0c59c6325418d0ef315688a692014caf952d3dcb5dbd04e794c0920c06c4e574
+  metadata.gz: 6df1a01ac720c72256be526321f9b30f93fcdde050ff6a0743c24bd53a64dd5b
+  data.tar.gz: d10ebba30ae8a59b7964536909315059c8d096dc1b3a9d0e735c7242db400153
 SHA512:
-  metadata.gz: 990ae6f7e507ec78e12bdbf0e67d7ee3e03ae196651add45af3e331fdcc19caa24cbbdc39fe9745dedd08a3463842ce5f23a31c39aa35945696bb62ef4a5d1c0
-  data.tar.gz: 87b946e0d25f380731b9d8db86f32565934793f175ccfbade88c2c3a8dc2fbc96e686a12db4fbd77b2941125ed48cc9da472ebeba1fa1dede7b5149a1938f1dd
+  metadata.gz: d623457be0fb4cc632f708365d53abbab2b7b647baf7ab37d18d6a05f21e321960e0632152ff2e60686d590e598cfa4333313cb6e31ad29868d2e4798be3e200
+  data.tar.gz: e9800dd0da6e0edf6ee8c01bf289700e7f61963fc2e379ea55ddd54dda7c52c8b85f0185c07fcd2a3d2aa8b92391a0bda9828c794f1960d16e39f1e10ed15210

data/lib/amplitude-experiment.rb

@@ -15,6 +15,9 @@ 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'
 
 # Amplitude Experiment Module

data/lib/experiment/error.rb

@@ -8,4 +8,18 @@ module AmplitudeExperiment
       @status_code = status_code
     end
   end
+
+  class CycleError < StandardError
+    # Raised when topological sorting encounters a cycle between flag dependencies.
+    attr_reader :path
+
+    def initialize(path)
+      super
+      @path = path
+    end
+
+    def to_s
+      "Detected a cycle between flags #{@path}"
+    end
+  end
 end

data/lib/experiment/local/assignment/assignment.rb

@@ -13,7 +13,9 @@ module AmplitudeExperiment
     def canonicalize
       sb = "#{@user&.user_id&.strip} #{@user&.device_id&.strip} "
       results.sort.to_h.each do |key, value|
-        sb += "#{key.strip} #{value['variant']&.fetch('key', '')&.strip} "
+        next unless value.key
+
+        sb += "#{key.strip} #{value.key&.strip} "
       end
       sb
     end

data/lib/experiment/local/assignment/assignment_service.rb

@@ -8,10 +8,10 @@ module AmplitudeExperiment
     end
 
     def track(assignment)
-      @amplitude.track(to_event(assignment)) if @assignment_filter.should_track(assignment)
+      @amplitude.track(AssignmentService.to_event(assignment)) if @assignment_filter.should_track(assignment)
     end
 
-    def to_event(assignment)
+    def self.to_event(assignment)
       event = AmplitudeAnalytics::BaseEvent.new(
         '[Experiment] Assignment',
         user_id: assignment.user.user_id,
@@ -20,28 +20,29 @@ module AmplitudeExperiment
         user_properties: {}
       )
 
-      assignment.results.each do |results_key, result|
-        event.event_properties["#{results_key}.variant"] = result['variant']['key']
-      end
-
       set = {}
       unset = {}
 
-      assignment.results.each do |results_key, result|
-        next if result['type'] == FLAG_TYPE_MUTUAL_EXCLUSION_GROUP
+      assignment.results.sort.to_h.each do |flag_key, variant|
+        next unless variant.key
+
+        version = variant.metadata['flagVersion'] if variant.metadata
+        segment_name = variant.metadata['segmentName'] if variant.metadata
+        flag_type = variant.metadata['flagType'] if variant.metadata
+        default = variant.metadata ? variant.metadata.fetch('default', false) : false
+        event.event_properties["#{flag_key}.variant"] = variant.key
+        event.event_properties["#{flag_key}.details"] = "v#{version} rule:#{segment_name}" if version && segment_name
+        next if flag_type == FLAG_TYPE_MUTUAL_EXCLUSION_GROUP
 
-        if result['isDefaultVariant']
-          unset["[Experiment] #{results_key}"] = '-'
+        if default
+          unset["[Experiment] #{flag_key}"] = '-'
         else
-          set["[Experiment] #{results_key}"] = result['variant']['key']
+          set["[Experiment] #{flag_key}"] = variant.key
         end
       end
-
       event.user_properties['$set'] = set
       event.user_properties['$unset'] = unset
-
       event.insert_id = "#{event.user_id} #{event.device_id} #{AmplitudeExperiment.hash_code(assignment.canonicalize)} #{assignment.timestamp / DAY_MILLIS}"
-
       event
     end
   end

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.
@@ -37,18 +36,38 @@ 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 = [])
+      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 = @flags_mutex.synchronize do
         @flags
       end
       return {} if flags.nil?
 
-      user_str = user.to_json
+      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
 
       @logger.debug("[Experiment] Evaluate: User: #{user_str} - Rules: #{flags}") if @config.debug
-      result = evaluation(flags, user_str)
+      result = evaluation(flags_json, user_str)
       @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.
@@ -69,29 +88,14 @@ module AmplitudeExperiment
 
     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
-      end
-      @assignment_service&.track(Assignment.new(user, assignments))
-      variants
-    end
-
     def run
       @is_running = true
       begin
-        flags = @fetcher.fetch_v1
+        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
+          @flags = flags_map
         end
       rescue StandardError => e
         @logger.error("[Experiment] Flag poller - error: #{e.message}")

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/local/fetcher.rb

@@ -31,6 +31,21 @@ module AmplitudeExperiment
       response.body
     end
 
+    def fetch_v2
+      # fetch flag_configs
+      headers = {
+        'Authorization' => "Api-Key #{@api_key}",
+        'Content-Type' => 'application/json;charset=utf-8',
+        '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)
+      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
+    end
+
     # Fetch local evaluation mode flag configs from the Experiment API server.
     # These flag configs can be used to perform local evaluation.
     #

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,14 @@ 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
+
     # @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 +97,11 @@ 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)
       @device_id = device_id
       @user_id = user_id
       @country = country
@@ -109,6 +119,8 @@ module AmplitudeExperiment
       @carrier = carrier
       @library = library
       @user_properties = user_properties
+      @groups = groups
+      @group_properties = group_properties
     end
 
     # Return User as Hash.
@@ -131,8 +143,10 @@ module AmplitudeExperiment
         device_model: @device_model,
         carrier: @carrier,
         library: @library,
-        user_properties: @user_properties
-      }
+        user_properties: @user_properties,
+        groups: @groups,
+        group_properties: @group_properties
+      }.compact
     end
 
     # Return user information as JSON string.

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,33 @@
+module AmplitudeExperiment
+  def self.user_to_evaluation_context(user)
+    user_groups = user.groups
+    user_group_properties = user.group_properties
+    user_hash = user.as_json.compact
+    user_hash.delete(:groups)
+    user_hash.delete(:group_properties)
+
+    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.to_sym] = { group_name: group_name }
+
+      next if user_group_properties.nil?
+
+      group_properties_type = user_group_properties[group_type.to_sym]
+      next if group_properties_type.nil? || !group_properties_type.is_a?(Hash)
+
+      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
+    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

data/lib/experiment/variant.rb

@@ -17,7 +17,9 @@ module AmplitudeExperiment
 
     # @param [String] value The value of the variant determined by the flag configuration.
     # @param [Object, nil] payload The attached payload, if any.
-    def initialize(value, payload = nil, key = nil, metadata = nil)
+    # @param [String] key The key of the variant determined by the flag configuration.
+    # @param [Object, nil] metadata The attached metadata, if any.
+    def initialize(value: nil, payload: nil, key: nil, metadata: nil)
       @key = key
       @value = value
       @payload = payload

data/lib/experiment/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: amplitude-experiment
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Amplitude
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-06-28 00:00:00.000000000 Z
+date: 2024-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -200,6 +200,9 @@ files:
 - lib/experiment/user.rb
 - lib/experiment/util/hash.rb
 - lib/experiment/util/lru_cache.rb
+- lib/experiment/util/topological_sort.rb
+- lib/experiment/util/user.rb
+- lib/experiment/util/variant.rb
 - lib/experiment/variant.rb
 - lib/experiment/version.rb
 homepage: https://github.com/amplitude/experiment-ruby-server