growthbook 0.3.0 → 1.0.0

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)
+      @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/util.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 require 'fnv'
+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,61 +42,41 @@ module Growthbook
       end
     end
 
-    def self.chooseVariation(userId, experiment)
-      testId = experiment.id
-      weights = experiment.getScaledWeights
+    def self.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
-    end
-
-    def self.hash(str)
-      (FNV.new.fnv1a_32(str) % 1000) / 1000.0
+      -1
     end
 
-    def self.in_namespace(userId, namespace)
-      n = hash("#{userId}__#{namespace[0]}")
+    def self.in_namespace(hash_value, namespace)
+      n = hash(seed: "__#{namespace[0]}", value: hash_value, version: 1)
       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 = 1, weights = [])
       # Make sure coverage is within bounds
       coverage = 1 if coverage.nil?
       coverage = 0 if coverage.negative?
       coverage = 1 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
@@ -101,23 +84,23 @@ module Growthbook
       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 == ''
 
@@ -132,7 +115,7 @@ module Growthbook
       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 +127,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,14 @@
 # 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/feature'
 require 'growthbook/feature_result'
 require 'growthbook/feature_rule'
 require 'growthbook/inline_experiment'
 require 'growthbook/inline_experiment_result'
-require 'growthbook/lookup_result'
-require 'growthbook/user'
 require 'growthbook/util'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: growthbook
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - GrowthBook
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-09-08 00:00:00.000000000 Z
+date: 2023-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -24,6 +24,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: simplecov-shields-badge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: fnv
   requirement: !ruby/object:Gem::Requirement
@@ -45,29 +73,19 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/growthbook.rb
-- lib/growthbook/client.rb
 - lib/growthbook/conditions.rb
 - lib/growthbook/context.rb
-- lib/growthbook/experiment.rb
-- lib/growthbook/experiment_result.rb
 - lib/growthbook/feature.rb
 - lib/growthbook/feature_result.rb
 - lib/growthbook/feature_rule.rb
 - lib/growthbook/inline_experiment.rb
 - lib/growthbook/inline_experiment_result.rb
-- lib/growthbook/lookup_result.rb
-- lib/growthbook/user.rb
 - lib/growthbook/util.rb
-- spec/cases.json
-- spec/client_spec.rb
-- spec/context_spec.rb
-- spec/json_spec.rb
-- spec/user_spec.rb
-- spec/util_spec.rb
 homepage: https://github.com/growthbook/growthbook-ruby
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -76,7 +94,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -87,10 +105,4 @@ rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: GrowthBook SDK for Ruby
-test_files:
-- spec/json_spec.rb
-- spec/user_spec.rb
-- spec/util_spec.rb
-- spec/context_spec.rb
-- spec/client_spec.rb
-- spec/cases.json
+test_files: []

data/lib/growthbook/client.rb

@@ -1,67 +0,0 @@
-module Growthbook
-  class Client
-    # @returns [Boolean]
-    attr_accessor :enabled
-    
-    # @returns [Array<Growthbook::Experiment>]
-    attr_accessor :experiments
-
-    # @param config [Hash]
-    # @option config [Boolean] :enabled (true) Set to false to disable all experiments
-    # @option config [Array<Growthbook::Experiment>] :experiments ([]) Array of Growthbook::Experiment objects
-    def initialize(config = {})
-      @enabled = config.has_key?(:enabled) ? config[:enabled] : true
-      @experiments = config[:experiments] || []
-      @resultsToTrack = []
-    end
-
-    # Look up a pre-configured experiment by id
-    # 
-    # @param id [String] The experiment id to look up
-    # @return [Growthbook::Experiment, nil] the experiment object or nil if not found
-    def getExperiment(id)
-      match = nil;
-      @experiments.each do |exp|
-        if exp.id == id
-          match = exp
-          break
-        end
-      end
-      return match
-    end
-
-    # Get a User object you can run experiments against
-    # 
-    # @param params [Hash]
-    # @option params [String, nil] :id The logged-in user id
-    # @option params [String, nil] :anonId The anonymous id (session id, ip address, cookie, etc.)
-    # @option params [Hash, nil] :attributes Any user attributes you want to use for experiment targeting
-    #    Values can be any type, even nested arrays and hashes
-    # @return [Growthbook::User] the User object
-    def user(params = {})
-      Growthbook::User.new(
-        params[:anonId] || nil,
-        params[:id] || nil,
-        params[:attributes] || nil,
-        self
-      )
-    end
-
-    def importExperimentsHash(experimentsHash = {})
-      @experiments = []
-      experimentsHash.each do |id, data|
-        variations = data["variations"]
-
-        options = {}
-        options[:coverage] = data["coverage"] if data.has_key?("coverage")
-        options[:weights] = data["weights"] if data.has_key?("weights")
-        options[:force] = data["force"] if data.has_key?("force")
-        options[:anon] = data["anon"] if data.has_key?("anon")
-        options[:targeting] = data["targeting"] if data.has_key?("targeting")
-        options[:data] = data["data"] if data.has_key?("data")
-
-        @experiments << Growthbook::Experiment.new(id, variations, options)
-      end
-    end
-  end
-end

data/lib/growthbook/experiment.rb

@@ -1,72 +0,0 @@
-module Growthbook
-  class Experiment
-    # @returns [String]
-    attr_accessor :id
-
-    # @returns [Integer]
-    attr_accessor :variations
-
-    # @returns [Float]
-    attr_accessor :coverage
-
-    # @returns [Array<Float>]
-    attr_accessor :weights
-
-    # @returns [Boolean]
-    attr_accessor :anon
-
-    # @returns [Array<String>]
-    attr_accessor :targeting
-
-    # @returns [Integer, nil]
-    attr_accessor :force
-
-    # @returns [Hash]
-    attr_accessor :data
-
-    # Constructor for an Experiment
-    # 
-    # @param id [String] The unique id for this experiment
-    # @param variations [Integer] The number of variations in this experiment (including the Control)
-    # @param options [Hash]
-    # @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(id, variations, options = {})
-      @id = id
-      @variations = variations
-      @coverage = options[:coverage] || 1
-      @weights = options[:weights] || getEqualWeights()
-      @force = options.has_key?(:force) ? options[:force] : nil
-      @anon = options.has_key?(:anon) ? options[:anon] : false
-      @targeting = options[:targeting] || []
-      @data = options[:data] || {}
-    end
-
-    def getScaledWeights
-      scaled = @weights.map do |n|
-        n*@coverage
-      end
-
-      return scaled
-    end
-
-    private
-
-    def getEqualWeights
-      weights = []
-      n = @variations
-      for i in 1..n
-        weights << (1.0 / n)
-      end
-      return weights
-    end
-  end
-end