ab-split 1.0.0

data/lib/split/experiment_catalog.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+module Split
+  class ExperimentCatalog
+    # Return all experiments
+    def self.all
+      # Call compact to prevent nil experiments from being returned -- seems to happen during gem upgrades
+      Split.redis.smembers(:experiments).map {|e| find(e)}.compact
+    end
+
+    # Return experiments without a winner (considered "active") first
+    def self.all_active_first
+      all.partition{|e| not e.winner}.map{|es| es.sort_by(&:name)}.flatten
+    end
+
+    def self.find(name)
+      return unless Split.redis.exists(name)
+      Experiment.new(name).tap { |exp| exp.load_from_redis }
+    end
+
+    def self.find_or_initialize(metric_descriptor, control = nil, *alternatives)
+      # Check if array is passed to ab_test
+      # e.g. ab_test('name', ['Alt 1', 'Alt 2', 'Alt 3'])
+      if control.is_a? Array and alternatives.length.zero?
+        control, alternatives = control.first, control[1..-1]
+      end
+
+      experiment_name_with_version, goals = normalize_experiment(metric_descriptor)
+      experiment_name = experiment_name_with_version.to_s.split(':')[0]
+      Split::Experiment.new(experiment_name,
+          :alternatives => [control].compact + alternatives, :goals => goals)
+    end
+
+    def self.find_or_create(metric_descriptor, control = nil, *alternatives)
+      experiment = find_or_initialize(metric_descriptor, control, *alternatives)
+      experiment.save
+    end
+
+    def self.normalize_experiment(metric_descriptor)
+      if Hash === metric_descriptor
+        experiment_name = metric_descriptor.keys.first
+        goals = Array(metric_descriptor.values.first)
+      else
+        experiment_name = metric_descriptor
+        goals = []
+      end
+      return experiment_name, goals
+    end
+    private_class_method :normalize_experiment
+
+  end
+end

data/lib/split/extensions/string.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+class String
+  # Constatntize is often provided by ActiveSupport, but ActiveSupport is not a dependency of Split.
+  unless method_defined?(:constantize)
+    def constantize
+      names = self.split('::')
+      names.shift if names.empty? || names.first.empty?
+
+      constant = Object
+      names.each do |name|
+        constant = constant.const_defined?(name) ? constant.const_get(name) : constant.const_missing(name)
+      end
+      constant
+    end
+  end
+end

data/lib/split/goals_collection.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+module Split
+  class GoalsCollection
+
+    def initialize(experiment_name, goals=nil)
+      @experiment_name = experiment_name
+      @goals = goals
+    end
+
+    def load_from_redis
+      Split.redis.lrange(goals_key, 0, -1)
+    end
+
+    def load_from_configuration
+      goals = Split.configuration.experiment_for(@experiment_name)[:goals]
+
+      if goals.nil?
+        goals = []
+      else
+        goals.flatten
+      end
+    end
+
+    def save
+      return false if @goals.nil?
+      RedisInterface.new.persist_list(goals_key, @goals)
+    end
+
+    def validate!
+      unless @goals.nil? || @goals.kind_of?(Array)
+        raise ArgumentError, 'Goals must be an array'
+      end
+    end
+
+    def delete
+      Split.redis.del(goals_key)
+    end
+
+    private
+
+    def goals_key
+      "#{@experiment_name}:goals"
+    end
+  end
+end

data/lib/split/helper.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+module Split
+  module Helper
+    OVERRIDE_PARAM_NAME = "ab_test"
+
+    module_function
+
+    def ab_test(metric_descriptor, control = nil, *alternatives)
+      begin
+        experiment = ExperimentCatalog.find_or_initialize(metric_descriptor, control, *alternatives)
+        alternative = if Split.configuration.enabled && !exclude_visitor?
+          experiment.save
+          raise(Split::InvalidExperimentsFormatError) unless (Split.configuration.experiments || {}).fetch(experiment.name.to_sym, {})[:combined_experiments].nil?
+          trial = Trial.new(:user => ab_user, :experiment => experiment,
+              :override => override_alternative(experiment.name), :exclude => exclude_visitor?,
+              :disabled => split_generically_disabled?)
+          alt = trial.choose!(self)
+          alt ? alt.name : nil
+        else
+          control_variable(experiment.control)
+        end
+      rescue Errno::ECONNREFUSED, Redis::BaseError, SocketError => e
+        raise(e) unless Split.configuration.db_failover
+        Split.configuration.db_failover_on_db_error.call(e)
+
+        if Split.configuration.db_failover_allow_parameter_override
+          alternative = override_alternative(experiment.name) if override_present?(experiment.name)
+          alternative = control_variable(experiment.control) if split_generically_disabled?
+        end
+      ensure
+        alternative ||= control_variable(experiment.control)
+      end
+
+      if block_given?
+        metadata = trial ? trial.metadata : {}
+        yield(alternative, metadata)
+      else
+        alternative
+      end
+    end
+
+    def reset!(experiment)
+      ab_user.delete(experiment.key)
+    end
+
+    def finish_experiment(experiment, options = {:reset => true})
+      return false if active_experiments[experiment.name].nil?
+      return true if experiment.has_winner?
+      should_reset = experiment.resettable? && options[:reset]
+      if ab_user[experiment.finished_key] && !should_reset
+        return true
+      else
+        alternative_name = ab_user[experiment.key]
+        trial = Trial.new(:user => ab_user, :experiment => experiment,
+              :alternative => alternative_name)
+        trial.complete!(options[:goals], self)
+
+        if should_reset
+          reset!(experiment)
+        else
+          ab_user[experiment.finished_key] = true
+        end
+      end
+    end
+
+    def ab_finished(metric_descriptor, options = {:reset => true})
+      return if exclude_visitor? || Split.configuration.disabled?
+      metric_descriptor, goals = normalize_metric(metric_descriptor)
+      experiments = Metric.possible_experiments(metric_descriptor)
+
+      if experiments.any?
+        experiments.each do |experiment|
+          finish_experiment(experiment, options.merge(:goals => goals))
+        end
+      end
+    rescue => e
+      raise unless Split.configuration.db_failover
+      Split.configuration.db_failover_on_db_error.call(e)
+    end
+
+    def ab_record_extra_info(metric_descriptor, key, value = 1)
+      return if exclude_visitor? || Split.configuration.disabled?
+      metric_descriptor, _ = normalize_metric(metric_descriptor)
+      experiments = Metric.possible_experiments(metric_descriptor)
+
+      if experiments.any?
+        experiments.each do |experiment|
+          alternative_name = ab_user[experiment.key]
+
+          if alternative_name
+            alternative = experiment.alternatives.find{|alt| alt.name == alternative_name}
+            alternative.record_extra_info(key, value) if alternative
+          end
+        end
+      end
+    rescue => e
+      raise unless Split.configuration.db_failover
+      Split.configuration.db_failover_on_db_error.call(e)
+    end
+
+    def ab_active_experiments()
+      ab_user.active_experiments
+    rescue => e
+      raise unless Split.configuration.db_failover
+      Split.configuration.db_failover_on_db_error.call(e)
+    end
+
+
+    def override_present?(experiment_name)
+      override_alternative(experiment_name)
+    end
+
+    def override_alternative(experiment_name)
+      defined?(params) && params[OVERRIDE_PARAM_NAME] && params[OVERRIDE_PARAM_NAME][experiment_name]
+    end
+
+    def split_generically_disabled?
+      defined?(params) && params['SPLIT_DISABLE']
+    end
+
+    def ab_user
+      @ab_user ||= User.new(self)
+    end
+
+    def exclude_visitor?
+      defined?(request) && (instance_exec(request, &Split.configuration.ignore_filter) || is_ignored_ip_address? || is_robot? || is_preview?)
+    end
+
+    def is_robot?
+      defined?(request) && request.user_agent =~ Split.configuration.robot_regex
+    end
+
+    def is_preview?
+      defined?(request) && defined?(request.headers) && request.headers['x-purpose'] == 'preview'
+    end
+
+    def is_ignored_ip_address?
+      return false if Split.configuration.ignore_ip_addresses.empty?
+
+      Split.configuration.ignore_ip_addresses.each do |ip|
+        return true if defined?(request) && (request.ip == ip || (ip.class == Regexp && request.ip =~ ip))
+      end
+      false
+    end
+
+    def active_experiments
+      ab_user.active_experiments
+    end
+
+    def normalize_metric(metric_descriptor)
+      if Hash === metric_descriptor
+        experiment_name = metric_descriptor.keys.first
+        goals = Array(metric_descriptor.values.first)
+      else
+        experiment_name = metric_descriptor
+        goals = []
+      end
+      return experiment_name, goals
+    end
+
+    def control_variable(control)
+      Hash === control ? control.keys.first.to_s : control.to_s
+    end
+  end
+end

data/lib/split/metric.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+module Split
+  class Metric
+    attr_accessor :name
+    attr_accessor :experiments
+
+    def initialize(attrs = {})
+      attrs.each do |key,value|
+        if self.respond_to?("#{key}=")
+          self.send("#{key}=", value)
+        end
+      end
+    end
+
+    def self.load_from_redis(name)
+      metric = Split.redis.hget(:metrics, name)
+      if metric
+        experiment_names = metric.split(',')
+
+        experiments = experiment_names.collect do |experiment_name|
+          Split::ExperimentCatalog.find(experiment_name)
+        end
+
+        Split::Metric.new(:name => name, :experiments => experiments)
+      else
+        nil
+      end
+    end
+
+    def self.load_from_configuration(name)
+      metrics = Split.configuration.metrics
+      if metrics && metrics[name]
+        Split::Metric.new(:experiments => metrics[name], :name => name)
+      else
+        nil
+      end
+    end
+
+    def self.find(name)
+      name = name.intern if name.is_a?(String)
+      metric = load_from_configuration(name)
+      metric = load_from_redis(name) if metric.nil?
+      metric
+    end
+
+    def self.find_or_create(attrs)
+      metric = find(attrs[:name])
+      unless metric
+        metric = new(attrs)
+        metric.save
+      end
+      metric
+    end
+
+    def self.all
+      redis_metrics = Split.redis.hgetall(:metrics).collect do |key, value|
+        find(key)
+      end
+      configuration_metrics = Split.configuration.metrics.collect do |key, value|
+        new(name: key, experiments: value)
+      end
+      redis_metrics | configuration_metrics
+    end
+
+    def self.possible_experiments(metric_name)
+      experiments = []
+      metric  = Split::Metric.find(metric_name)
+      if metric
+        experiments << metric.experiments
+      end
+      experiment = Split::ExperimentCatalog.find(metric_name)
+      if experiment
+        experiments << experiment
+      end
+      experiments.flatten
+    end
+
+    def save
+      Split.redis.hset(:metrics, name, experiments.map(&:name).join(','))
+    end
+
+    def complete!
+      experiments.each do |experiment|
+        experiment.complete!
+      end
+    end
+
+    def self.normalize_metric(label)
+      if Hash === label
+        metric_name = label.keys.first
+        goals = label.values.first
+      else
+        metric_name = label
+        goals = []
+      end
+      return metric_name, goals
+    end
+    private_class_method :normalize_metric
+
+  end
+end

data/lib/split/persistence.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Split
+  module Persistence
+    require 'split/persistence/cookie_adapter'
+    require 'split/persistence/dual_adapter'
+    require 'split/persistence/redis_adapter'
+    require 'split/persistence/session_adapter'
+
+    ADAPTERS = {
+      :cookie => Split::Persistence::CookieAdapter,
+      :session => Split::Persistence::SessionAdapter
+    }.freeze
+
+    def self.adapter
+      if persistence_config.is_a?(Symbol)
+        ADAPTERS.fetch(persistence_config) { raise Split::InvalidPersistenceAdapterError }
+      else
+        persistence_config
+      end
+    end
+
+    def self.persistence_config
+      Split.configuration.persistence
+    end
+    private_class_method :persistence_config
+  end
+end

data/lib/split/persistence/cookie_adapter.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+require "json"
+
+module Split
+  module Persistence
+    class CookieAdapter
+
+      def initialize(context)
+        @context = context
+        @request, @response = context.request, context.response
+        @cookies = @request.cookies
+        @expires = Time.now + cookie_length_config
+      end
+
+      def [](key)
+        hash[key.to_s]
+      end
+
+      def []=(key, value)
+        set_cookie(hash.merge!(key.to_s => value))
+      end
+
+      def delete(key)
+        set_cookie(hash.tap { |h| h.delete(key.to_s) })
+      end
+
+      def keys
+        hash.keys
+      end
+
+      private
+
+      def set_cookie(value = {})
+        cookie_key = :split.to_s
+        cookie_value = default_options.merge(value: JSON.generate(value))
+        if action_dispatch?
+          # The "send" is necessary when we call ab_test from the controller
+          # and thus @context is a rails controller, because then "cookies" is
+          # a private method.
+          @context.send(:cookies)[cookie_key] = cookie_value
+        else
+          set_cookie_via_rack(cookie_key, cookie_value)
+        end
+      end
+
+      def default_options
+        { expires: @expires, path: '/' }
+      end
+
+      def set_cookie_via_rack(key, value)
+        delete_cookie_header!(@response.header, key, value)
+        Rack::Utils.set_cookie_header!(@response.header, key, value)
+      end
+
+      # Use Rack::Utils#make_delete_cookie_header after Rack 2.0.0
+      def delete_cookie_header!(header, key, value)
+        cookie_header = header['Set-Cookie']
+        case cookie_header
+        when nil, ''
+          cookies = []
+        when String
+          cookies = cookie_header.split("\n")
+        when Array
+          cookies = cookie_header
+        end
+
+        cookies.reject! { |cookie| cookie =~ /\A#{Rack::Utils.escape(key)}=/ }
+        header['Set-Cookie'] = cookies.join("\n")
+      end
+
+      def hash
+        @hash ||= begin
+          if cookies = @cookies[:split.to_s]
+            begin
+              JSON.parse(cookies)
+            rescue JSON::ParserError
+              {}
+            end
+          else
+            {}
+          end
+        end
+      end
+
+      def cookie_length_config
+        Split.configuration.persistence_cookie_length
+      end
+
+      def action_dispatch?
+        defined?(Rails) && @response.is_a?(ActionDispatch::Response)
+      end
+    end
+  end
+end