growthbook 0.3.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f6c9a059b34fad58095b5e0ea6b3710d7b427617a4cd4f9c7ddc8fdebd2a1da
-  data.tar.gz: c93b9e289a8c950dc3cfa5974062634e7c11f6123e7fd5e94f6ff8c88d262566
+  metadata.gz: f5919b4bd1e6564233d0fb61f00f2fcc5fee175f3122a35e9815df47ebdaeb6f
+  data.tar.gz: 88bf0372e161e261a536fd8953f858e9f4ad60592a96cbfb8e3baa523414cbca
 SHA512:
-  metadata.gz: 0f1c46dac7d0e9dccc8641f67d7dbbe8d2af91ec18a4cf0fdcb13701042e0fad55bbcf35b91c330506816fa59cbb0129a8ae5a7f3fb103b308735268f3638937
-  data.tar.gz: c38fe86529984df54ee57560b01591c99a20b616f02d8296e9e81a7c1fc56d6755096c675e96e94a52c57c5e9e77435b497aed2d4a3ebb4c0cdcbd78f7d8085b
+  metadata.gz: 771a1f4fd4eeb6acb92606e67677d65717e3b3a98de80528d2adef3cce17f183a6524af1da74cb09ff18d195a062dd1c882c208cb8dfeaf631603c54b7d128e9
+  data.tar.gz: 3b2386b97c64ea3609ad907005d90baec0a25e7b51d45bbd973490d66a204255d5a31d1d435da406cfcd8f3443a28bb8163e6f649af114999b847cbe822f2593

data/lib/growthbook/conditions.rb

@@ -3,6 +3,8 @@
 require 'json'
 
 module Growthbook
+  # internal use only
+  # Utils for condition evaluation
   class Conditions
     # Evaluate a targeting conditions hash against an attributes hash
     # Both attributes and conditions only have string keys (no symbols)
@@ -25,9 +27,8 @@ module Growthbook
       when Array
         return condition.map { |v| parse_condition(v) }
       when Hash
-        return condition.map { |k, v| [k.to_s, parse_condition(v)] }.to_h
+        return condition.to_h { |k, v| [k.to_s, parse_condition(v)] }
       end
-
       condition
     end
 
@@ -47,7 +48,7 @@ module Growthbook
       true
     end
 
-    def self.is_operator_object(obj)
+    def self.operator_object?(obj)
       obj.each do |key, _value|
         return false if key[0] != '$'
       end
@@ -58,7 +59,7 @@ module Growthbook
       return 'string' if attribute_value.is_a? String
       return 'number' if attribute_value.is_a? Integer
       return 'number' if attribute_value.is_a? Float
-      return 'boolean' if attribute_value == true || attribute_value == false
+      return 'boolean' if [true, false].include?(attribute_value)
       return 'array' if attribute_value.is_a? Array
       return 'null' if attribute_value.nil?
 
@@ -66,22 +67,22 @@ module Growthbook
     end
 
     def self.get_path(attributes, path)
+      path = path.to_s if path.is_a?(Symbol)
+
       parts = path.split('.')
       current = attributes
 
       parts.each do |value|
-        if current && current.is_a?(Hash) && current.key?(value)
-          current = current[value]
-        else
-          return nil
-        end
+        return nil unless current.is_a?(Hash) && current&.key?(value)
+
+        current = current[value]
       end
 
       current
     end
 
     def self.eval_condition_value(condition_value, attribute_value)
-      if condition_value.is_a?(Hash) && is_operator_object(condition_value)
+      if condition_value.is_a?(Hash) && operator_object?(condition_value)
         condition_value.each do |key, value|
           return false unless eval_operator_condition(key, attribute_value, value)
         end
@@ -94,7 +95,7 @@ module Growthbook
       return false unless attribute_value.is_a? Array
 
       attribute_value.each do |item|
-        if is_operator_object(condition)
+        if operator_object?(condition)
           return true if eval_condition_value(condition, item)
         elsif eval_condition(item, condition)
           return true
@@ -147,10 +148,10 @@ module Growthbook
         true
       when '$exists'
         exists = !attribute_value.nil?
-        if !condition_value
-          !exists
-        else
+        if condition_value
           exists
+        else
+          !exists
         end
       when '$type'
         condition_value == get_type(attribute_value)

data/lib/growthbook/context.rb

@@ -1,9 +1,34 @@
 # frozen_string_literal: true
 
 module Growthbook
+  # Context object passed into the GrowthBook constructor.
   class Context
-    attr_accessor :enabled, :url, :qa_mode, :listener
-    attr_reader :attributes, :features, :impressions, :forced_variations, :forced_features
+    # @return [true, false] Switch to globally disable all experiments. Default true.
+    attr_accessor :enabled
+
+    # @return [String] The URL of the current page
+    attr_accessor :url
+
+    # @return [true, false, nil] If true, random assignment is disabled and only explicitly forced variations are used.
+    attr_accessor :qa_mode
+
+    # @return [Growthbook::TrackingCallback] An object that responds to `on_experiment_viewed(GrowthBook::InlineExperiment, GrowthBook::InlineExperimentResult)`
+    attr_accessor :listener
+
+    # @return [Hash] Map of user attributes that are used to assign variations
+    attr_reader :attributes
+
+    # @return [Hash] Feature definitions (usually pulled from an API or cache)
+    attr_reader :features
+
+    # @return [Hash] Force specific experiments to always assign a specific variation (used for QA)
+    attr_reader :forced_variations
+
+    # @return [Hash[String, Growthbook::InlineExperimentResult]] Tracked impressions
+    attr_reader :impressions
+
+    # @return [Hash[String, Any]] Forced feature values
+    attr_reader :forced_features
 
     def initialize(options = {})
       @features = {}
@@ -13,14 +38,19 @@ module Growthbook
       @enabled = true
       @impressions = {}
 
-      options.each do |key, value|
-        case key.to_sym
+      options.transform_keys(&:to_sym).each do |key, value|
+        case key
         when :enabled
           @enabled = value
         when :attributes
           self.attributes = value
         when :url
           @url = value
+        when :decryption_key
+          nil
+        when :encrypted_features
+          decrypted = decrypted_features_from_options(options)
+          self.features = decrypted unless decrypted.nil?
         when :features
           self.features = value
         when :forced_variations, :forcedVariations
@@ -40,6 +70,8 @@ module Growthbook
     def features=(features)
       @features = {}
 
+      return if features.nil?
+
       features.each do |k, v|
         # Convert to a Feature object if it's not already
         v = Growthbook::Feature.new(v) unless v.is_a? Growthbook::Feature
@@ -62,42 +94,49 @@ module Growthbook
 
     def eval_feature(key)
       # Forced in the context
-      if @forced_features.key?(key.to_s)
-        return get_feature_result(@forced_features[key.to_s], 'override') 
-      end
+      return get_feature_result(@forced_features[key.to_s], 'override', nil, nil) if @forced_features.key?(key.to_s)
 
       # Return if we can't find the feature definition
       feature = get_feature(key)
-      return get_feature_result(nil, 'unknownFeature') unless feature
+      return get_feature_result(nil, 'unknownFeature', nil, nil) unless feature
 
       feature.rules.each do |rule|
         # Targeting condition
-        next if rule.condition && !condition_passes(rule.condition)
-
-        # Rollout or forced value rule
-        if rule.is_force?
-          unless rule.coverage.nil?
-            hash_value = get_attribute(rule.hash_attribute || 'id').to_s
-            next if hash_value.length.zero?
-
-            n = Growthbook::Util.hash(hash_value + key)
-            next if n > rule.coverage
-          end
-          return get_feature_result(rule.force, 'force')
+        next if rule.condition && !condition_passes?(rule.condition)
+
+        # If there are filters for who is included (e.g. namespaces)
+        next if rule.filters && filtered_out?(rule.filters || [])
+
+        # If this is a percentage rollout, skip if not included
+        if rule.force?
+          seed = rule.seed || key
+          hash_attribute = rule.hash_attribute || 'id'
+          included_in_rollout = included_in_rollout?(
+            seed: seed.to_s,
+            hash_attribute: hash_attribute,
+            range: rule.range,
+            coverage: rule.coverage,
+            hash_version: rule.hash_version
+          )
+          next unless included_in_rollout
+
+          return get_feature_result(rule.force, 'force', nil, nil)
         end
         # Experiment rule
-        next unless rule.is_experiment?
+        next unless rule.experiment?
 
         exp = rule.to_experiment(key)
+        next if exp.nil?
+
         result = _run(exp, key)
 
-        next unless result.in_experiment
+        next unless result.in_experiment && !result.passthrough
 
         return get_feature_result(result.value, 'experiment', exp, result)
       end
 
       # Fallback
-      get_feature_result(feature.default_value || nil, 'defaultValue')
+      get_feature_result(feature.default_value.nil? ? nil : feature.default_value, 'defaultValue', nil, nil)
     end
 
     def run(exp)
@@ -119,58 +158,80 @@ module Growthbook
 
     private
 
-    def _run(exp, feature_id="")
+    def _run(exp, feature_id = '')
       key = exp.key
 
       # 1. If experiment doesn't have enough variations, return immediately
-      return get_experiment_result(exp, -1, false, feature_id) if exp.variations.length < 2
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if exp.variations.length < 2
 
       # 2. If context is disabled, return immediately
-      return get_experiment_result(exp, -1, false, feature_id) unless @enabled
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) unless @enabled
 
       # 3. If forced via URL querystring
-      if @url
-        qsOverride = Util.get_query_string_override(key, @url, exp.variations.length)
-        return get_experiment_result(exp, qsOverride, false, feature_id) unless qsOverride.nil?
+      override_url = @url
+      unless override_url.nil?
+        qs_override = Util.get_query_string_override(key, override_url, exp.variations.length)
+        return get_experiment_result(exp, qs_override, hash_used: false, feature_id: feature_id) unless qs_override.nil?
       end
 
       # 4. If variation is forced in the context, return the forced value
-      return get_experiment_result(exp, @forced_variations[key.to_s], false, feature_id) if @forced_variations.key?(key.to_s)
+      if @forced_variations.key?(key.to_s)
+        return get_experiment_result(
+          exp,
+          @forced_variations[key.to_s],
+          hash_used: false,
+          feature_id: feature_id
+        )
+      end
 
       # 5. Exclude if not active
-      return get_experiment_result(exp, -1, false, feature_id) unless exp.active
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) unless exp.active
 
       # 6. Get hash_attribute/value and return if empty
       hash_attribute = exp.hash_attribute || 'id'
       hash_value = get_attribute(hash_attribute).to_s
-      return get_experiment_result(exp, -1, false, feature_id) if hash_value.length.zero?
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if hash_value.empty?
 
-      # 7. Exclude if user not in namespace
-      return get_experiment_result(exp, -1, false, feature_id) if exp.namespace && !Growthbook::Util.in_namespace(hash_value, exp.namespace)
+      # 7. Exclude if user is filtered out (used to be called "namespace")
+      if exp.filters
+        return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if filtered_out?(exp.filters || [])
+      elsif exp.namespace && !Growthbook::Util.in_namespace?(hash_value, exp.namespace)
+        return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id)
+      end
 
       # 8. Exclude if condition is false
-      return get_experiment_result(exp, -1, false, feature_id) if exp.condition && !condition_passes(exp.condition)
+      if exp.condition && !condition_passes?(exp.condition)
+        return get_experiment_result(
+          exp,
+          -1,
+          hash_used: false,
+          feature_id: feature_id
+        )
+      end
 
-      # 9. Calculate bucket ranges and choose one
-      ranges = Growthbook::Util.get_bucket_ranges(
+      # 9. Get bucket ranges and choose variation
+      ranges = exp.ranges || Growthbook::Util.get_bucket_ranges(
         exp.variations.length,
         exp.coverage,
         exp.weights
       )
-      n = Growthbook::Util.hash(hash_value + key)
+      seed = exp.seed || key || ''
+      n = Growthbook::Util.get_hash(seed: seed, value: hash_value, version: exp.hash_version || 1)
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if n.nil?
+
       assigned = Growthbook::Util.choose_variation(n, ranges)
 
       # 10. Return if not in experiment
-      return get_experiment_result(exp, -1, false, feature_id) if assigned.negative?
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if assigned.negative?
 
       # 11. Experiment has a forced variation
-      return get_experiment_result(exp, exp.force, false, feature_id) unless exp.force.nil?
+      return get_experiment_result(exp, exp.force, hash_used: false, feature_id: feature_id) unless exp.force.nil?
 
       # 12. Exclude if in QA mode
-      return get_experiment_result(exp, -1, false, feature_id) if @qa_mode
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if @qa_mode
 
       # 13. Build the result object
-      result = get_experiment_result(exp, assigned, true, feature_id)
+      result = get_experiment_result(exp, assigned, hash_used: true, feature_id: feature_id, bucket: n)
 
       # 14. Fire tracking callback
       track_experiment(exp, result)
@@ -187,11 +248,13 @@ module Growthbook
       new_hash
     end
 
-    def condition_passes(condition)
+    def condition_passes?(condition)
+      return false if condition.nil?
+
       Growthbook::Conditions.eval_condition(@attributes, condition)
     end
 
-    def get_experiment_result(experiment, variation_index = -1, hash_used = false, feature_id = "")
+    def get_experiment_result(experiment, variation_index = -1, hash_used: false, feature_id: '', bucket: nil)
       in_experiment = true
       if variation_index.negative? || variation_index >= experiment.variations.length
         variation_index = 0
@@ -200,12 +263,29 @@ module Growthbook
 
       hash_attribute = experiment.hash_attribute || 'id'
       hash_value = get_attribute(hash_attribute)
+      meta = experiment.meta ? experiment.meta[variation_index] : {}
+
+      result = Growthbook::InlineExperimentResult.new(
+        {
+          key: meta['key'] || variation_index,
+          in_experiment: in_experiment,
+          variation_id: variation_index,
+          value: experiment.variations[variation_index],
+          hash_used: hash_used,
+          hash_attribute: hash_attribute,
+          hash_value: hash_value,
+          feature_id: feature_id,
+          bucket: bucket,
+          name: meta['name']
+        }
+      )
+
+      result.passthrough = true if meta['passthrough']
 
-      Growthbook::InlineExperimentResult.new(hash_used, in_experiment, variation_index,
-                                             experiment.variations[variation_index], hash_attribute, hash_value, feature_id)
+      result
     end
 
-    def get_feature_result(value, source, experiment = nil, experiment_result = nil)
+    def get_feature_result(value, source, experiment, experiment_result)
       Growthbook::FeatureResult.new(value, source, experiment, experiment_result)
     end
 
@@ -224,10 +304,52 @@ module Growthbook
     end
 
     def track_experiment(experiment, result)
-      if @listener && @listener.respond_to?(:on_experiment_viewed)
-        @listener.on_experiment_viewed(experiment, result)
+      return if listener.nil?
+
+      @listener.on_experiment_viewed(experiment, result) if @listener.respond_to?(:on_experiment_viewed)
+      @impressions[experiment.key] = result unless experiment.key.nil?
+    end
+
+    def included_in_rollout?(seed:, hash_attribute:, hash_version:, range:, coverage:)
+      return true if range.nil? && coverage.nil?
+
+      hash_value = get_attribute(hash_attribute)
+
+      return false if hash_value.empty?
+
+      n = Growthbook::Util.get_hash(seed: seed, value: hash_value, version: hash_version || 1)
+      return false if n.nil?
+
+      return Growthbook::Util.in_range?(n, range) if range
+      return n <= coverage if coverage
+
+      true
+    end
+
+    def filtered_out?(filters)
+      filters.any? do |filter|
+        hash_value = get_attribute(filter['attribute'] || 'id')
+
+        if hash_value.empty?
+          false
+        else
+          n = Growthbook::Util.get_hash(seed: filter['seed'] || '', value: hash_value, version: filter['hashVersion'] || 2)
+
+          return true if n.nil?
+
+          filter['ranges'].none? { |range| Growthbook::Util.in_range?(n, range) }
+        end
       end
-      @impressions[experiment.key] = result
+    end
+
+    def decrypted_features_from_options(options)
+      decrypted_features = DecryptionUtil.decrypt(options[:encrypted_features], key: options[:decryption_key])
+
+      return nil if decrypted_features.nil?
+
+      JSON.parse(decrypted_features)
+    rescue StandardError
+      nil
     end
   end
 end

data/lib/growthbook/decryption_util.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'openssl'
+
+module Growthbook
+  # Utils for working with encrypted feature payloads.
+  class DecryptionUtil
+    # @return [String, nil] The decrypted payload, or nil if it fails to decrypt
+    def self.decrypt(payload, key:)
+      return nil if payload.nil?
+      return nil unless payload.include?('.')
+
+      parts = payload.split('.')
+      return nil if parts.length != 2
+
+      iv = parts[0]
+      decoded_iv = Base64.strict_decode64(iv)
+      decoded_key = Base64.strict_decode64(key)
+
+      cipher_text = parts[1]
+      decoded_cipher_text = Base64.strict_decode64(cipher_text)
+
+      cipher = OpenSSL::Cipher.new('aes-128-cbc')
+
+      cipher.decrypt
+      cipher.key = decoded_key
+      cipher.iv = decoded_iv
+
+      cipher.update(decoded_cipher_text) + cipher.final
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/growthbook/feature.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Growthbook
+  # The feature with a generic value type.
   class Feature
     # @return [Any , nil]
     attr_reader :default_value
@@ -9,9 +10,9 @@ module Growthbook
     attr_reader :rules
 
     def initialize(feature)
-      @default_value = getOption(feature, :defaultValue)
+      @default_value = get_option(feature, :defaultValue)
 
-      rules = getOption(feature, :rules)
+      rules = get_option(feature, :rules)
 
       @rules = []
       rules&.each do |rule|
@@ -31,7 +32,7 @@ module Growthbook
 
     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/feature_repository.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module Growthbook
+  # Optional class for fetching features from the GrowthBook API
+  class FeatureRepository
+    # [String] The SDK endpoint
+    attr_reader :endpoint
+
+    # [String, nil] Optional key for decrypting an encrypted payload
+    attr_reader :decryption_key
+
+    # Parsed features JSON
+    attr_reader :features_json
+
+    def initialize(endpoint:, decryption_key:)
+      @endpoint = endpoint
+      @decryption_key = decryption_key
+      @features_json = {}
+    end
+
+    def fetch
+      uri = URI(endpoint)
+      res = Net::HTTP.get_response(uri)
+
+      @response = res.is_a?(Net::HTTPSuccess) ? res.body : nil
+
+      return nil if response.nil?
+
+      if use_decryption?
+        parsed_decrypted_response
+      else
+        parsed_plain_text_response
+      end
+    rescue StandardError
+      nil
+    end
+
+    def fetch!
+      fetch
+
+      raise FeatureFetchError if response.nil?
+      raise FeatureParseError if features_json.nil? || features_json.empty?
+
+      features_json
+    end
+
+    private
+
+    attr_reader :response
+
+    def use_decryption?
+      !decryption_key.nil?
+    end
+
+    def parsed_plain_text_response
+      @features_json = parsed_response['features'] unless parsed_response.nil?
+    rescue StandardError
+      nil
+    end
+
+    def parsed_decrypted_response
+      k = decryption_key
+      return nil if k.nil?
+
+      decrypted_str = Growthbook::DecryptionUtil.decrypt(parsed_response['encryptedFeatures'], key: k)
+      @features_json = JSON.parse(decrypted_str) unless decrypted_str.nil?
+    rescue StandardError
+      nil
+    end
+
+    def parsed_response
+      res = response
+      return {} if res.nil?
+
+      JSON.parse(res)
+    rescue StandardError
+      {}
+    end
+
+    class FeatureFetchError < StandardError; end
+
+    class FeatureParseError < StandardError; end
+  end
+end

data/lib/growthbook/feature_result.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Growthbook
+  # Result of a feature evaluation
   class FeatureResult
     # The assigned value of the feature
     # @return [Any, nil]
@@ -19,11 +20,11 @@ module Growthbook
     attr_reader :source
 
     # The experiment used to decide the feature value
-    # @return [Growthbook.Experiment, nil]
+    # @return [Growthbook::InlineExperiment, nil]
     attr_reader :experiment
 
     # The result of the experiment
-    # @return [Growthbook.ExperimentResult, nil]
+    # @return [Growthbook::InlineExperimentResult, nil]
     attr_reader :experiment_result
 
     def initialize(