growthbook 0.3.0 → 1.1.0

data/lib/growthbook/feature_rule.rb

@@ -1,37 +1,82 @@
 # frozen_string_literal: true
 
 module Growthbook
+  # Internal class that overrides the default value of a Feature based on a set of requirements.
   class FeatureRule
-    # @return [Hash , nil]
+    # @return [Hash , nil] Optional targeting condition
     attr_reader :condition
-    # @return [Float , nil]
+
+    # @return [Float , nil] What percent of users should be included in the experiment (between 0 and 1, inclusive)
     attr_reader :coverage
-    # @return [T , nil]
+
+    # @return [T , nil] Immediately force a specific value (ignore every other option besides condition and coverage)
     attr_reader :force
-    # @return [T[] , nil]
+
+    # @return [T[] , nil] Run an experiment (A/B test) and randomly choose between these variations
     attr_reader :variations
-    # @return [String , nil]
+
+    # @return [String , nil] The globally unique tracking key for the experiment (default to the feature key)
     attr_reader :key
-    # @return [Float[] , nil]
+
+    # @return [Float[] , nil] How to weight traffic between variations. Must add to 1.
     attr_reader :weights
-    # @return [Array , nil]
+
+    # @return [String , nil] Adds the experiment to a namespace
     attr_reader :namespace
-    # @return [String , nil]
+
+    # @return [String , nil] What user attribute should be used to assign variations (defaults to id)
     attr_reader :hash_attribute
 
+    # @return [Integer , nil] The hash version to use (default to 1)
+    attr_reader :hash_version
+
+    # @return [BucketRange , nil] A more precise version of coverage
+    attr_reader :range
+
+    # @return [BucketRanges[] , nil] Ranges for experiment variations
+    attr_reader :ranges
+
+    # @return [VariationMeta[] , nil] Meta info about the experiment variations
+    attr_reader :meta
+
+    # @return [Filter[] , nil] Array of filters to apply to the rule
+    attr_reader :filters
+
+    # @return [String , nil]  Seed to use for hashing
+    attr_reader :seed
+
+    # @return [String , nil] Human-readable name for the experiment
+    attr_reader :name
+
+    # @return [String , nil] The phase id of the experiment
+    attr_reader :phase
+
+    # @return [TrackData[] , nil] Array of tracking calls to fire
+    attr_reader :tracks
+
     def initialize(rule)
-      @coverage = getOption(rule, :coverage)
-      @force = getOption(rule, :force)
-      @variations = getOption(rule, :variations)
-      @key = getOption(rule, :key)
-      @weights = getOption(rule, :weights)
-      @namespace = getOption(rule, :namespace)
-      @hash_attribute = getOption(rule, :hash_attribute) || getOption(rule, :hashAttribute)
-
-      cond = getOption(rule, :condition)
+      @coverage = get_option(rule, :coverage)
+      @force = get_option(rule, :force)
+      @variations = get_option(rule, :variations)
+      @key = get_option(rule, :key)
+      @weights = get_option(rule, :weights)
+      @namespace = get_option(rule, :namespace)
+      @hash_attribute = get_option(rule, :hash_attribute) || get_option(rule, :hashAttribute)
+      @hash_version = get_option(rule, :hash_version) || get_option(rule, :hashVersion)
+      @range = get_option(rule, :range)
+      @ranges = get_option(rule, :ranges)
+      @meta = get_option(rule, :meta)
+      @filters = get_option(rule, :filters)
+      @seed = get_option(rule, :seed)
+      @name = get_option(rule, :name)
+      @phase = get_option(rule, :phase)
+      @tracks = get_option(rule, :tracks)
+
+      cond = get_option(rule, :condition)
       @condition = Growthbook::Conditions.parse_condition(cond) unless cond.nil?
     end
 
+    # @return [Growthbook::InlineExperiment, nil]
     def to_experiment(feature_key)
       return nil unless @variations
 
@@ -41,34 +86,51 @@ module Growthbook
         coverage: @coverage,
         weights: @weights,
         hash_attribute: @hash_attribute,
-        namespace: @namespace
+        hash_version: @hash_version,
+        namespace: @namespace,
+        meta: @meta,
+        ranges: @ranges,
+        filters: @filters,
+        name: @name,
+        phase: @phase,
+        seed: @seed
       )
     end
 
-    def is_experiment?
-      !!@variations
+    def experiment?
+      return false if @variations.nil?
+
+      !@variations&.empty?
     end
 
-    def is_force?
-      !is_experiment? && !@force.nil?
+    def force?
+      !experiment? && !@force.nil?
     end
 
     def to_json(*_args)
-      res = {}
-      res['condition'] = @condition unless @condition.nil?
-      res['coverage'] = @coverage unless @coverage.nil?
-      res['force'] = @force unless @force.nil?
-      res['variations'] = @variations unless @variations.nil?
-      res['key'] = @key unless @key.nil?
-      res['weights'] = @weights unless @weights.nil?
-      res['namespace'] = @namespace unless @namespace.nil?
-      res['hashAttribute'] = @hash_attribute unless @hash_attribute.nil?
-      res
+      {
+        'condition'     => @condition,
+        'coverage'      => @coverage,
+        'force'         => @force,
+        'variations'    => @variations,
+        'key'           => @key,
+        'weights'       => @weights,
+        'namespace'     => @namespace,
+        'hashAttribute' => @hash_attribute,
+        'range'         => @range,
+        'ranges'        => @ranges,
+        'meta'          => @meta,
+        'filters'       => @filters,
+        'seed'          => @seed,
+        'name'          => @name,
+        'phase'         => @phase,
+        'tracks'        => @tracks
+      }.compact
     end
 
     private
 
-    def getOption(hash, key)
+    def get_option(hash, key)
       return hash[key.to_sym] if hash.key?(key.to_sym)
       return hash[key.to_s] if hash.key?(key.to_s)
 

data/lib/growthbook/fnv.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# FNV
+# {https://github.com/jakedouglas/fnv-ruby Source}
+class FNV
+  INIT32  = 0x811c9dc5
+  INIT64  = 0xcbf29ce484222325
+  PRIME32 = 0x01000193
+  PRIME64 = 0x100000001b3
+  MOD32   = 4_294_967_296
+  MOD64   = 18_446_744_073_709_551_616
+
+  def fnv1a_32(data)
+    hash = INIT32
+
+    data.bytes.each do |byte|
+      hash = hash ^ byte
+      hash = (hash * PRIME32) % MOD32
+    end
+
+    hash
+  end
+end

data/lib/growthbook/inline_experiment.rb

@@ -1,80 +1,103 @@
 # frozen_string_literal: true
 
 module Growthbook
+  # Class for creating an inline experiment for evaluating
   class InlineExperiment
-    # @returns [String]
+    # @return [String] The globally unique identifier for the experiment
     attr_accessor :key
 
-    # @returns [Any]
+    # @return [Array<String, Integer, Hash>] The different variations to choose between
     attr_accessor :variations
 
-    # @returns [Bool]
-    attr_accessor :active
-
-    # @returns [Integer, nil]
-    attr_accessor :force
-
-    # @returns [Array<Float>, nil]
+    # @return [Array<Float>] How to weight traffic between variations. Must add to 1.
     attr_accessor :weights
 
-    # @returns [Float]
+    # @return [true, false] If set to false, always return the control (first variation)
+    attr_accessor :active
+
+    # @return [Float] What percent of users should be included in the experiment (between 0 and 1, inclusive)
     attr_accessor :coverage
 
-    # @returns [Hash, nil]
+    # @return [Array<Hash>] Array of ranges, one per variation
+    attr_accessor :ranges
+
+    # @return [Hash] Optional targeting condition
     attr_accessor :condition
 
-    # @returns [Array]
+    # @return [String, nil] Adds the experiment to a namespace
     attr_accessor :namespace
 
-    # @returns [String]
+    # @return [integer, nil] All users included in the experiment will be forced into the specific variation index
+    attr_accessor :force
+
+    # @return [String] What user attribute should be used to assign variations (defaults to id)
     attr_accessor :hash_attribute
 
-    # Constructor for an Experiment
-    #
-    # @param options [Hash]
-    # @option options [Array<Any>] :variations The variations to pick between
-    # @option options [String] :key The unique identifier for this experiment
-    # @option options [Float] :coverage (1.0) The percent of elegible traffic to include in the experiment
-    # @option options [Array<Float>] :weights The relative weights of the variations.
-    #    Length must be the same as the number of variations. Total should add to 1.0.
-    #    Default is an even split between variations
-    # @option options [Boolean] :anon (false) If false, the experiment uses the logged-in user id for bucketing
-    #    If true, the experiment uses the anonymous id for bucketing
-    # @option options [Array<String>] :targeting Array of targeting rules in the format "key op value"
-    #    where op is one of: =, !=, <, >, ~, !~
-    # @option options [Integer, nil] :force If an integer, force all users to get this variation
-    # @option options [Hash] :data Data to attach to the variations
-    def initialize(options = {})
-      @key = getOption(options, :key, '').to_s
-      @variations = getOption(options, :variations, [])
-      @active = getOption(options, :active, true)
-      @force = getOption(options, :force)
-      @weights = getOption(options, :weights)
-      @coverage = getOption(options, :coverage, 1)
-      @condition = getOption(options, :condition)
-      @namespace = getOption(options, :namespace)
-      @hash_attribute = getOption(options, :hash_attribute) || getOption(options, :hashAttribute) || 'id'
-    end
+    # @return [Integer] The hash version to use (default to 1)
+    attr_accessor :hash_version
 
-    def getOption(hash, key, default = nil)
-      return hash[key.to_sym] if hash.key?(key.to_sym)
-      return hash[key.to_s] if hash.key?(key.to_s)
+    # @return [Array<Hash>] Meta info about the variations
+    attr_accessor :meta
 
-      default
+    # @return [Array<Hash>] Array of filters to apply
+    attr_accessor :filters
+
+    # @return [String, nil] The hash seed to use
+    attr_accessor :seed
+
+    # @return [String] Human-readable name for the experiment
+    attr_accessor :name
+
+    # @return [String, nil] Id of the current experiment phase
+    attr_accessor :phase
+
+    def initialize(options = {})
+      @key = get_option(options, :key, '').to_s
+      @variations = get_option(options, :variations, [])
+      @weights = get_option(options, :weights)
+      @active = get_option(options, :active, true)
+      @coverage = get_option(options, :coverage, 1.0)
+      @ranges = get_option(options, :ranges)
+      @condition = get_option(options, :condition)
+      @namespace = get_option(options, :namespace)
+      @force = get_option(options, :force)
+      @hash_attribute = get_option(options, :hash_attribute) || get_option(options, :hashAttribute) || 'id'
+      @hash_version = get_option(options, :hash_version) || get_option(options, :hashVersion)
+      @meta = get_option(options, :meta)
+      @filters = get_option(options, :filters)
+      @seed = get_option(options, :seed)
+      @name = get_option(options, :name)
+      @phase = get_option(options, :phase)
     end
 
     def to_json(*_args)
       res = {}
       res['key'] = @key
       res['variations'] = @variations
-      res['active'] = @active if @active != true && !@active.nil?
-      res['force'] = @force unless @force.nil?
       res['weights'] = @weights unless @weights.nil?
+      res['active'] = @active if @active != true && !@active.nil?
       res['coverage'] = @coverage if @coverage != 1 && !@coverage.nil?
-      res['condition'] = @condition unless @condition.nil?
-      res['namespace'] = @namespace unless @namespace.nil?
+      res['ranges'] = @ranges
+      res['condition'] = @condition
+      res['namespace'] = @namespace
+      res['force'] = @force unless @force.nil?
       res['hashAttribute'] = @hash_attribute if @hash_attribute != 'id' && !@hash_attribute.nil?
-      res
+      res['hashVersion'] = @hash_version
+      res['meta'] = @meta
+      res['filters'] = @filters
+      res['seed'] = @seed
+      res['name'] = @name
+      res['phase'] = @phase
+      res.compact
+    end
+
+    private
+
+    def get_option(hash, key, default = nil)
+      return hash[key.to_sym] if hash.key?(key.to_sym)
+      return hash[key.to_s] if hash.key?(key.to_s)
+
+      default
     end
   end
 end

data/lib/growthbook/inline_experiment_result.rb

@@ -1,62 +1,81 @@
 # frozen_string_literal: true
 
 module Growthbook
+  # Result of running an experiment.
   class InlineExperimentResult
-    # Whether or not the user is in the experiment
-    # @return [Bool]
+    # @return [Boolean] Whether or not the user is part of the experiment
     attr_reader :in_experiment
 
-    # The array index of the assigned variation
-    # @return [Integer]
+    # @return [Integer] The array index of the assigned variation
     attr_reader :variation_id
 
-    # The assigned variation value
-    # @return [Any]
+    # @return [Any] The array value of the assigned variation
     attr_reader :value
 
-    # If the variation was randomly assigned based on user attribute hashes
-    # @return [Bool]
+    # @return [Bool] If a hash was used to assign a variation
     attr_reader :hash_used
 
-    # The attribute used to split traffic
-    # @return [String]
+    # @return [String] The user attribute used to assign a variation
     attr_reader :hash_attribute
 
-    # The value of the hashAttribute
-    # @return [String]
+    # @return [String] The value of that attribute
     attr_reader :hash_value
 
+    # @return [String, nil] The id of the feature (if any) that the experiment came from
     attr_reader :feature_id
 
-    def initialize(
-      hash_used,
-      in_experiment,
-      variation_id,
-      value,
-      hash_attribute,
-      hash_value,
-      feature_id
-    )
-
-      @hash_used = hash_used
-      @in_experiment = in_experiment
-      @variation_id = variation_id
-      @value = value
-      @hash_attribute = hash_attribute
-      @hash_value = hash_value
-      @feature_id = feature_id
+    # @return [String] The unique key for the assigned variation
+    attr_reader :key
+
+    # @return [Float] The hash value used to assign a variation (float from 0 to 1)
+    attr_reader :bucket
+
+    # @return [String , nil] Human-readable name for the experiment
+    attr_reader :name
+
+    # @return [Boolean]  Used for holdout groups
+    attr_accessor :passthrough
+
+    def initialize(options = {})
+      @key = options[:key]
+      @in_experiment = options[:in_experiment]
+      @variation_id = options[:variation_id]
+      @value = options[:value]
+      @hash_used = options[:hash_used]
+      @hash_attribute = options[:hash_attribute]
+      @hash_value = options[:hash_value]
+      @feature_id = options[:feature_id]
+      @bucket = options[:bucket]
+      @name = options[:name]
+      @passthrough = options[:passthrough]
+    end
+
+    # If the variation was randomly assigned based on user attribute hashes
+    # @return [Bool]
+    def hash_used?
+      @hash_used
+    end
+
+    # Whether or not the user is in the experiment
+    # @return [Bool]
+    def in_experiment?
+      @in_experiment
     end
 
     def to_json(*_args)
-      res = {}
-      res['inExperiment'] = @in_experiment
-      res['hashUsed'] = @hash_used
-      res['variationId'] = @variation_id
-      res['value'] = @value
-      res['hashAttribute'] = @hash_attribute
-      res['hashValue'] = @hash_value
-      res['featureId'] = @feature_id.to_s
-      res
+      {
+        'inExperiment'  => @in_experiment,
+        'variationId'   => @variation_id,
+        'value'         => @value,
+        'hashUsed'      => @hash_used,
+        'hashAttribute' => @hash_attribute,
+        'hashValue'     => @hash_value,
+        'featureId'     => @feature_id.to_s,
+        'key'           => @key.to_s,
+        'bucket'        => @bucket,
+        'name'          => @name,
+        'passthrough'   => @passthrough
+      }.compact
     end
   end
 end

data/lib/growthbook/tracking_callback.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Growthbook
+  # Extendable class that can be used as the tracking callback
+  class TrackingCallback
+    def on_experiment_viewed(_experiment, _result); end
+  end
+end

data/lib/growthbook/util.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
-require 'fnv'
+require 'base64'
+require 'bigdecimal'
+require 'bigdecimal/util'
 
 module Growthbook
+  # internal use only
   class Util
-    def self.checkRule(actual, op, desired)
+    def self.check_rule(actual, op, desired)
       # Check if both strings are numeric so we can do natural ordering
       # for greater than / less than operators
       numeric = begin
@@ -15,9 +18,9 @@ module Growthbook
 
       case op
       when '='
-        numeric ? Float(actual) == Float(desired) : actual == desired
+        numeric ? Float(actual).to_d == Float(desired).to_d : actual == desired
       when '!='
-        numeric ? Float(actual) != Float(desired) : actual != desired
+        numeric ? Float(actual).to_d != Float(desired).to_d : actual != desired
       when '>'
         numeric ? Float(actual) > Float(desired) : actual > desired
       when '<'
@@ -39,100 +42,86 @@ module Growthbook
       end
     end
 
-    def self.chooseVariation(userId, experiment)
-      testId = experiment.id
-      weights = experiment.getScaledWeights
+    # @return [Float, nil] Hash, or nil if the hash version is invalid
+    def self.get_hash(seed:, value:, version:)
+      return (FNV.new.fnv1a_32(value + seed) % 1000) / 1000.0 if version == 1
+      return (FNV.new.fnv1a_32(FNV.new.fnv1a_32(seed + value).to_s) % 10_000) / 10_000.0 if version == 2
 
-      # Hash the user id and testName to a number from 0 to 1
-      n = (FNV.new.fnv1a_32(userId + testId) % 1000) / 1000.0
-
-      cumulativeWeight = 0
-
-      match = -1
-      i = 0
-      weights.each do |weight|
-        cumulativeWeight += weight
-        if n < cumulativeWeight
-          match = i
-          break
-        end
-        i += 1
-      end
-
-      match
+      nil
     end
 
-    def self.hash(str)
-      (FNV.new.fnv1a_32(str) % 1000) / 1000.0
-    end
+    def self.in_namespace?(hash_value, namespace)
+      return false if namespace.nil?
+
+      n = get_hash(seed: "__#{namespace[0]}", value: hash_value, version: 1)
+      return false if n.nil?
 
-    def self.in_namespace(userId, namespace)
-      n = hash("#{userId}__#{namespace[0]}")
       n >= namespace[1] && n < namespace[2]
     end
 
-    def self.get_equal_weights(numVariations)
-      return [] if numVariations < 1
+    def self.get_equal_weights(num_variations)
+      return [] if num_variations < 1
 
       weights = []
-      (1..numVariations).each do |_i|
-        weights << (1.0 / numVariations)
+      (1..num_variations).each do |_i|
+        weights << (1.0 / num_variations)
       end
       weights
     end
 
     # Determine bucket ranges for experiment variations
-    def self.get_bucket_ranges(numVariations, coverage = 1, weights = [])
+    def self.get_bucket_ranges(num_variations, coverage, weights)
       # Make sure coverage is within bounds
-      coverage = 1 if coverage.nil?
-      coverage = 0 if coverage.negative?
-      coverage = 1 if coverage > 1
+      coverage = 1.0 if coverage.nil?
+      coverage = 0.0 if coverage.negative?
+      coverage = 1.0 if coverage > 1
 
       # Default to equal weights
-      weights = get_equal_weights(numVariations) if !weights || weights.length != numVariations
+      weights = get_equal_weights(num_variations) if !weights || weights.length != num_variations
 
       # If weights don't add up to 1 (or close to it), default to equal weights
       total = weights.sum
-      weights = get_equal_weights(numVariations) if total < 0.99 || total > 1.01
+      weights = get_equal_weights(num_variations) if total < 0.99 || total > 1.01
 
       # Convert weights to ranges
-      cumulative = 0
+      cumulative = 0.0
       ranges = []
       weights.each do |w|
         start = cumulative
         cumulative += w
-        ranges << [start, start + coverage * w]
+        ranges << [start, start + (coverage * w)]
       end
 
       ranges
     end
 
     # Chose a variation based on a hash and range
-    def self.choose_variation(n, ranges)
+    def self.choose_variation(num, ranges)
       ranges.each_with_index do |range, i|
-        return i if n >= range[0] && n < range[1]
+        return i if num >= range[0] && num < range[1]
       end
       -1
     end
 
     # Get an override variation from a url querystring
     # e.g. http://localhost?my-test=1 will return `1` for id `my-test`
-    def self.get_query_string_override(id, url, numVariations)
+    def self.get_query_string_override(id, url, num_variations)
       # Skip if url is empty
-      return nil if url == ''
+      return nil if url == '' || id.nil?
 
       # Parse out the query string
       parsed = URI(url)
-      return nil unless parsed.query
+      parsed_query = parsed.query
+      return nil if parsed_query.nil?
 
-      qs = URI.decode_www_form(parsed.query)
+      qs = URI.decode_www_form(parsed_query)
 
       # Look for `id` in the querystring and get the value
       vals = qs.assoc(id)
       return nil unless vals
 
       val = vals.last
-      return nill unless val
+      return nil unless val
 
       # Parse the value as an integer
       n = begin
@@ -144,9 +133,13 @@ module Growthbook
       # Make sure the integer is within range
       return nil if n.nil?
       return nil if n.negative?
-      return nil if n >= numVariations
+      return nil if n >= num_variations
 
       n
     end
+
+    def self.in_range?(num, range)
+      num >= range[0] && num < range[1]
+    end
   end
 end

data/lib/growthbook.rb

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
+# The GrowthBook SDK
 module Growthbook
 end
 
-require 'growthbook/client'
 require 'growthbook/conditions'
 require 'growthbook/context'
-require 'growthbook/experiment'
-require 'growthbook/experiment_result'
+require 'growthbook/decryption_util'
 require 'growthbook/feature'
+require 'growthbook/feature_repository'
 require 'growthbook/feature_result'
 require 'growthbook/feature_rule'
+require 'growthbook/fnv'
 require 'growthbook/inline_experiment'
 require 'growthbook/inline_experiment_result'
-require 'growthbook/lookup_result'
-require 'growthbook/user'
+require 'growthbook/tracking_callback'
 require 'growthbook/util'