amplitude-experiment 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c79062c9e6a6f0877449f49dab03aa2445cf31700ecb92010f88d5779759d73a
-  data.tar.gz: 1cf7d73b53cb125ecfaa6987bb4569d7416c5b02e194ef9f90be65c8da0b2fe6
+  metadata.gz: 6d05f9400e7dd25e87eb6f372c0c1c7fa5c083fe392a75dd25152e0ad0c010a1
+  data.tar.gz: 19df424d3a56c5a44d6495282f3e1f5022e1a50c47b4a5e0fcfc53c0535576ea
 SHA512:
-  metadata.gz: 45e8a5540fc7a0e9a9213bdfe7c8828137d35aee0ab6d5dab50e79cac47bf858f11db626a545f131c7a5e48bf05b04b9b82944441d5c307d9562fd42973e5edb
-  data.tar.gz: ffebca0974025ed2e983b106468be3806eb724cb5f0a2723d0f2782b67005d679ca8cfec4edb1b5236578a855472838a1f20e81d7641e362301d35fc5bfec32c
+  metadata.gz: 4e2e412e261f918990f23890200e9dc7b2cf0ed5b52e38fe585f10a3bd84f3b2d062c21a60dbf6811fdf27c395635f214f433d5dfb77c5573e3ae7e82a803352
+  data.tar.gz: 3bde003e6e5cb0d8b139218d408c5235949bed823f6973fb3f45f3eb542d7adfc7cdfe74f416bf62f06d6cd910eace6490bb6e4e3e6a0b7ef8f4abe686c854b4

data/amplitude-experiment.gemspec

@@ -14,21 +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.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

@@ -14,7 +14,6 @@ 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'
@@ -28,6 +27,12 @@ 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/deployment/deployment_runner.rb

@@ -60,9 +60,9 @@ module AmplitudeExperiment
 
     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']) }
+      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|

data/lib/experiment/evaluation/evaluation.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+module Evaluation
+  # Engine for evaluating feature flags based on context
+  class Engine
+    def evaluate(context, flags)
+      results = {}
+      target = {
+        'context' => context,
+        'result' => results
+      }
+
+      flags.each do |flag|
+        variant = evaluate_flag(target, flag)
+        results[flag.key] = variant if variant
+      end
+
+      results
+    end
+
+    private
+
+    def evaluate_flag(target, flag)
+      result = nil
+      flag.segments.each do |segment|
+        result = evaluate_segment(target, flag, segment)
+        next unless result
+
+        # Merge all metadata into the result
+        metadata = {}
+        metadata.merge!(flag.metadata) if flag.metadata
+        metadata.merge!(segment.metadata) if segment.metadata
+        metadata.merge!(result.metadata) if result.metadata
+        result.metadata = metadata
+        break
+      end
+      result
+    end
+
+    def evaluate_segment(target, flag, segment)
+      if segment.conditions
+        match = evaluate_conditions(target, segment.conditions)
+        if match
+          variant_key = bucket(target, segment)
+          variant_key ? flag.variants[variant_key] : nil
+        end
+      else
+        # Null conditions always match
+        variant_key = bucket(target, segment)
+        variant_key ? flag.variants[variant_key] : nil
+      end
+    end
+
+    def evaluate_conditions(target, conditions)
+      # Outer list logic is "or" (||)
+      conditions.any? do |inner_conditions|
+        match = true
+        inner_conditions.each do |condition|
+          match = match_condition(target, condition)
+          break unless match
+        end
+        match
+      end
+    end
+
+    def match_condition(target, condition)
+      prop_value = Evaluation.select(target, condition.selector)
+      # Special matching for null properties and set type prop values and operators
+      if !prop_value
+        match_null(condition.op, condition.values)
+      elsif set_operator?(condition.op)
+        prop_value_string_list = coerce_string_array(prop_value)
+        return false unless prop_value_string_list
+
+        match_set(prop_value_string_list, condition.op, condition.values)
+      else
+        prop_value_string = coerce_string(prop_value)
+        if prop_value_string
+          match_string(prop_value_string, condition.op, condition.values)
+        else
+          false
+        end
+      end
+    end
+
+    def get_hash(key)
+      Murmur3.hash32x86(key)
+    end
+
+    def bucket(target, segment)
+      unless segment.bucket
+        # Null bucket means segment is fully rolled out
+        return segment.variant
+      end
+
+      bucketing_value = coerce_string(Evaluation.select(target, segment.bucket.selector))
+      if !bucketing_value || bucketing_value.empty?
+        # Null or empty bucketing value cannot be bucketed
+        return segment.variant
+      end
+
+      key_to_hash = "#{segment.bucket.salt}/#{bucketing_value}"
+      hash = get_hash(key_to_hash)
+      allocation_value = hash % 100
+      distribution_value = (hash / 100).floor
+
+      segment.bucket.allocations.each do |allocation|
+        allocation_start = allocation.range[0]
+        allocation_end = allocation.range[1]
+        next unless allocation_value >= allocation_start && allocation_value < allocation_end
+
+        allocation.distributions.each do |distribution|
+          distribution_start = distribution.range[0]
+          distribution_end = distribution.range[1]
+          return distribution.variant if distribution_value >= distribution_start && distribution_value < distribution_end
+        end
+      end
+
+      segment.variant
+    end
+
+    def match_null(op, filter_values)
+      contains_none = contains_none?(filter_values)
+      case op
+      when Operator::IS, Operator::CONTAINS, Operator::LESS_THAN,
+        Operator::LESS_THAN_EQUALS, Operator::GREATER_THAN,
+        Operator::GREATER_THAN_EQUALS, Operator::VERSION_LESS_THAN,
+        Operator::VERSION_LESS_THAN_EQUALS, Operator::VERSION_GREATER_THAN,
+        Operator::VERSION_GREATER_THAN_EQUALS, Operator::SET_IS,
+        Operator::SET_CONTAINS, Operator::SET_CONTAINS_ANY
+        contains_none
+      when Operator::IS_NOT, Operator::DOES_NOT_CONTAIN,
+        Operator::SET_DOES_NOT_CONTAIN, Operator::SET_DOES_NOT_CONTAIN_ANY
+        !contains_none
+      else
+        false
+      end
+    end
+
+    def match_set(prop_values, op, filter_values)
+      case op
+      when Operator::SET_IS
+        set_equals?(prop_values, filter_values)
+      when Operator::SET_IS_NOT
+        !set_equals?(prop_values, filter_values)
+      when Operator::SET_CONTAINS
+        matches_set_contains_all?(prop_values, filter_values)
+      when Operator::SET_DOES_NOT_CONTAIN
+        !matches_set_contains_all?(prop_values, filter_values)
+      when Operator::SET_CONTAINS_ANY
+        matches_set_contains_any?(prop_values, filter_values)
+      when Operator::SET_DOES_NOT_CONTAIN_ANY
+        !matches_set_contains_any?(prop_values, filter_values)
+      else
+        false
+      end
+    end
+
+    def match_string(prop_value, op, filter_values)
+      case op
+      when Operator::IS
+        matches_is?(prop_value, filter_values)
+      when Operator::IS_NOT
+        !matches_is?(prop_value, filter_values)
+      when Operator::CONTAINS
+        matches_contains?(prop_value, filter_values)
+      when Operator::DOES_NOT_CONTAIN
+        !matches_contains?(prop_value, filter_values)
+      when Operator::LESS_THAN, Operator::LESS_THAN_EQUALS,
+        Operator::GREATER_THAN, Operator::GREATER_THAN_EQUALS
+        matches_comparable?(prop_value, op, filter_values,
+                            method(:parse_number),
+                            method(:comparator))
+      when Operator::VERSION_LESS_THAN, Operator::VERSION_LESS_THAN_EQUALS,
+        Operator::VERSION_GREATER_THAN, Operator::VERSION_GREATER_THAN_EQUALS
+        matches_comparable?(prop_value, op, filter_values,
+                            SemanticVersion.method(:parse),
+                            method(:comparator))
+      when Operator::REGEX_MATCH
+        matches_regex?(prop_value, filter_values)
+      when Operator::REGEX_DOES_NOT_MATCH
+        !matches_regex?(prop_value, filter_values)
+      else
+        false
+      end
+    end
+
+    def matches_is?(prop_value, filter_values)
+      if contains_booleans?(filter_values)
+        lower = prop_value.downcase
+        return filter_values.any? { |value| value.downcase == lower } if %w[true false].include?(lower)
+      end
+      filter_values.any? { |value| prop_value == value }
+    end
+
+    def matches_contains?(prop_value, filter_values)
+      filter_values.any? do |filter_value|
+        prop_value.downcase.include?(filter_value.downcase)
+      end
+    end
+
+    def matches_comparable?(prop_value, op, filter_values, type_transformer, type_comparator)
+      prop_value_transformed = type_transformer.call(prop_value)
+      filter_values_transformed = filter_values
+                                  .map { |filter_value| type_transformer.call(filter_value) }
+                                  .compact
+
+      if !prop_value_transformed || filter_values_transformed.empty?
+        filter_values.any? { |filter_value| comparator(prop_value, op, filter_value) }
+      else
+        filter_values_transformed.any? do |filter_value_transformed|
+          type_comparator.call(prop_value_transformed, op, filter_value_transformed)
+        end
+      end
+    end
+
+    def comparator(prop_value, op, filter_value)
+      case op
+      when Operator::LESS_THAN, Operator::VERSION_LESS_THAN
+        prop_value < filter_value
+      when Operator::LESS_THAN_EQUALS, Operator::VERSION_LESS_THAN_EQUALS
+        prop_value <= filter_value
+      when Operator::GREATER_THAN, Operator::VERSION_GREATER_THAN
+        prop_value > filter_value
+      when Operator::GREATER_THAN_EQUALS, Operator::VERSION_GREATER_THAN_EQUALS
+        prop_value >= filter_value
+      else
+        false
+      end
+    end
+
+    def matches_regex?(prop_value, filter_values)
+      filter_values.any? { |filter_value| !!(Regexp.new(filter_value) =~ prop_value) }
+    end
+
+    def contains_none?(filter_values)
+      filter_values.any? { |filter_value| filter_value == '(none)' }
+    end
+
+    def contains_booleans?(filter_values)
+      filter_values.any? do |filter_value|
+        case filter_value.downcase
+        when 'true', 'false'
+          true
+        else
+          false
+        end
+      end
+    end
+
+    def parse_number(value)
+      Float(value)
+    rescue StandardError
+      nil
+    end
+
+    def coerce_string(value)
+      return nil if value.nil?
+      return value.to_json if value.is_a?(Hash)
+
+      value.to_s
+    end
+
+    def coerce_string_array(value)
+      if value.is_a?(Array)
+        value.map { |e| coerce_string(e) }.compact
+      else
+        string_value = value.to_s
+        begin
+          parsed_value = JSON.parse(string_value)
+          if parsed_value.is_a?(Array)
+            parsed_value.map { |e| coerce_string(e) }.compact
+          else
+            s = coerce_string(string_value)
+            s ? [s] : nil
+          end
+        rescue JSON::ParserError
+          s = coerce_string(string_value)
+          s ? [s] : nil
+        end
+      end
+    end
+
+    def set_operator?(op)
+      case op
+      when Operator::SET_IS, Operator::SET_IS_NOT,
+        Operator::SET_CONTAINS, Operator::SET_DOES_NOT_CONTAIN,
+        Operator::SET_CONTAINS_ANY, Operator::SET_DOES_NOT_CONTAIN_ANY
+        true
+      else
+        false
+      end
+    end
+
+    def set_equals?(xa, ya)
+      xs = Set.new(xa)
+      ys = Set.new(ya)
+      xs.size == ys.size && ys.all? { |y| xs.include?(y) }
+    end
+
+    def matches_set_contains_all?(prop_values, filter_values)
+      return false if prop_values.length < filter_values.length
+
+      filter_values.all? { |filter_value| matches_is?(filter_value, prop_values) }
+    end
+
+    def matches_set_contains_any?(prop_values, filter_values)
+      filter_values.any? { |filter_value| matches_is?(filter_value, prop_values) }
+    end
+  end
+end

data/lib/experiment/evaluation/flag.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Evaluation
+  class Distribution
+    attr_accessor :variant, :range
+
+    def self.from_hash(hash)
+      new.tap do |dist|
+        dist.variant = hash['variant']
+        dist.range = hash['range']
+      end
+    end
+  end
+
+  class Allocation
+    attr_accessor :range, :distributions
+
+    def self.from_hash(hash)
+      new.tap do |alloc|
+        alloc.range = hash['range']
+        alloc.distributions = hash['distributions']&.map { |d| Distribution.from_hash(d) }
+      end
+    end
+  end
+
+  class Condition
+    attr_accessor :selector, :op, :values
+
+    def self.from_hash(hash)
+      new.tap do |cond|
+        cond.selector = hash['selector']
+        cond.op = hash['op']
+        cond.values = hash['values']
+      end
+    end
+  end
+
+  class Bucket
+    attr_accessor :selector, :salt, :allocations
+
+    def self.from_hash(hash)
+      new.tap do |bucket|
+        bucket.selector = hash['selector']
+        bucket.salt = hash['salt']
+        bucket.allocations = hash['allocations']&.map { |a| Allocation.from_hash(a) }
+      end
+    end
+  end
+
+  class Segment
+    attr_accessor :bucket, :conditions, :variant, :metadata
+
+    def self.from_hash(hash)
+      new.tap do |segment|
+        segment.bucket = hash['bucket'] && Bucket.from_hash(hash['bucket'])
+        segment.conditions = hash['conditions']&.map { |c| c.map { |inner| Condition.from_hash(inner) } }
+        segment.variant = hash['variant']
+        segment.metadata = hash['metadata']
+      end
+    end
+  end
+
+  class Variant
+    attr_accessor :key, :value, :payload, :metadata
+
+    def [](key)
+      instance_variable_get("@#{key}")
+    end
+
+    def self.from_hash(hash)
+      new.tap do |variant|
+        variant.key = hash['key']
+        variant.value = hash['value']
+        variant.payload = hash['payload']
+        variant.metadata = hash['metadata']
+      end
+    end
+  end
+
+  class Flag
+    attr_accessor :key, :variants, :segments, :dependencies, :metadata
+
+    def self.from_hash(hash)
+      new.tap do |flag|
+        flag.key = hash['key']
+        flag.variants = hash['variants'].transform_values { |v| Variant.from_hash(v) }
+        flag.segments = hash['segments'].map { |s| Segment.from_hash(s) }
+        flag.dependencies = hash['dependencies']
+        flag.metadata = hash['metadata']
+      end
+    end
+
+    # Used for testing
+    def ==(other)
+      key == other.key
+    end
+  end
+
+  module Operator
+    IS = 'is'
+    IS_NOT = 'is not'
+    CONTAINS = 'contains'
+    DOES_NOT_CONTAIN = 'does not contain'
+    LESS_THAN = 'less'
+    LESS_THAN_EQUALS = 'less or equal'
+    GREATER_THAN = 'greater'
+    GREATER_THAN_EQUALS = 'greater or equal'
+    VERSION_LESS_THAN = 'version less'
+    VERSION_LESS_THAN_EQUALS = 'version less or equal'
+    VERSION_GREATER_THAN = 'version greater'
+    VERSION_GREATER_THAN_EQUALS = 'version greater or equal'
+    SET_IS = 'set is'
+    SET_IS_NOT = 'set is not'
+    SET_CONTAINS = 'set contains'
+    SET_DOES_NOT_CONTAIN = 'set does not contain'
+    SET_CONTAINS_ANY = 'set contains any'
+    SET_DOES_NOT_CONTAIN_ANY = 'set does not contain any'
+    REGEX_MATCH = 'regex match'
+    REGEX_DOES_NOT_MATCH = 'regex does not match'
+  end
+end

data/lib/experiment/evaluation/murmur3.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Implements 32-bit x86 MurmurHash3
+class Murmur3
+  C1_32 = -0x3361d2af
+  C2_32 = 0x1b873593
+  R1_32 = 15
+  R2_32 = 13
+  M_32 = 5
+  N_32 = -0x19ab949c
+
+  class << self
+    def hash32x86(input, seed = 0)
+      data = string_to_utf8_bytes(input)
+      length = data.length
+      n_blocks = length >> 2
+      hash = seed
+
+      # Process body
+      n_blocks.times do |i|
+        index = i << 2
+        k = read_int_le(data, index)
+        hash = mix32(k, hash)
+      end
+
+      # Process tail
+      index = n_blocks << 2
+      k1 = 0
+
+      case length - index
+      when 3
+        k1 ^= data[index + 2] << 16
+        k1 ^= data[index + 1] << 8
+        k1 ^= data[index]
+        k1 = (k1 * C1_32) & 0xffffffff
+        k1 = rotate_left(k1, R1_32)
+        k1 = (k1 * C2_32) & 0xffffffff
+        hash ^= k1
+      when 2
+        k1 ^= data[index + 1] << 8
+        k1 ^= data[index]
+        k1 = (k1 * C1_32) & 0xffffffff
+        k1 = rotate_left(k1, R1_32)
+        k1 = (k1 * C2_32) & 0xffffffff
+        hash ^= k1
+      when 1
+        k1 ^= data[index]
+        k1 = (k1 * C1_32) & 0xffffffff
+        k1 = rotate_left(k1, R1_32)
+        k1 = (k1 * C2_32) & 0xffffffff
+        hash ^= k1
+      end
+
+      hash ^= length
+      fmix32(hash) & 0xffffffff
+    end
+
+    private
+
+    def mix32(k, hash)
+      k = (k * C1_32) & 0xffffffff
+      k = rotate_left(k, R1_32)
+      k = (k * C2_32) & 0xffffffff
+      hash ^= k
+      hash = rotate_left(hash, R2_32)
+      ((hash * M_32) + N_32) & 0xffffffff
+    end
+
+    def fmix32(hash)
+      hash ^= hash >> 16
+      hash = (hash * -0x7a143595) & 0xffffffff
+      hash ^= hash >> 13
+      hash = (hash * -0x3d4d51cb) & 0xffffffff
+      hash ^= hash >> 16
+      hash
+    end
+
+    def rotate_left(x, n, width = 32)
+      n = n % width if n > width
+      mask = (0xffffffff << (width - n)) & 0xffffffff
+      r = ((x & mask) >> (width - n)) & 0xffffffff
+      ((x << n) | r) & 0xffffffff
+    end
+
+    def read_int_le(data, index = 0)
+      n = (data[index] << 24) |
+          (data[index + 1] << 16) |
+          (data[index + 2] << 8) |
+          data[index + 3]
+      reverse_bytes(n)
+    end
+
+    def reverse_bytes(n)
+      ((n & -0x1000000) >> 24) |
+        ((n & 0x00ff0000) >> 8) |
+        ((n & 0x0000ff00) << 8) |
+        ((n & 0x000000ff) << 24)
+    end
+
+    def string_to_utf8_bytes(str)
+      str.encode('UTF-8').bytes
+    end
+  end
+end

data/lib/experiment/evaluation/select.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Selects a value from a nested object using an array of selector keys
+module Evaluation
+  def self.select(selectable, selector)
+    return nil if selector.nil? || selector.empty?
+
+    selector.each do |selector_element|
+      return nil if selector_element.nil? || selectable.nil?
+
+      selectable = selectable[selector_element]
+    end
+
+    selectable.nil? ? nil : selectable
+  end
+end

data/lib/experiment/evaluation/semantic_version.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+class SemanticVersion
+  include Comparable
+
+  attr_reader :major, :minor, :patch, :pre_release
+
+  MAJOR_MINOR_REGEX = '(\d+)\.(\d+)'
+  PATCH_REGEX = '(\d+)'
+  PRERELEASE_REGEX = '(-(([-\w]+\.?)*))?'
+  VERSION_PATTERN = /^#{MAJOR_MINOR_REGEX}(\.#{PATCH_REGEX}#{PRERELEASE_REGEX})?$/.freeze
+
+  def initialize(major, minor, patch, pre_release = nil)
+    @major = major
+    @minor = minor
+    @patch = patch
+    @pre_release = pre_release
+  end
+
+  def self.parse(version)
+    return nil if version.nil?
+
+    match = VERSION_PATTERN.match(version)
+    return nil unless match
+
+    major = match[1].to_i
+    minor = match[2].to_i
+    patch = match[4]&.to_i || 0
+    pre_release = match[5]
+
+    new(major, minor, patch, pre_release)
+  end
+
+  def <=>(other)
+    return nil unless other.is_a?(SemanticVersion)
+
+    result = major <=> other.major
+    return result unless result.zero?
+
+    result = minor <=> other.minor
+    return result unless result.zero?
+
+    result = patch <=> other.patch
+    return result unless result.zero?
+
+    return 1 if !pre_release && other.pre_release
+    return -1 if pre_release && !other.pre_release
+    return 0 if !pre_release && !other.pre_release
+
+    pre_release <=> other.pre_release
+  end
+end