trailguide 0.1.0

data/lib/trail_guide/algorithms.rb

@@ -0,0 +1,24 @@
+require "trail_guide/algorithms/weighted"
+require "trail_guide/algorithms/distributed"
+require "trail_guide/algorithms/bandit"
+require "trail_guide/algorithms/random"
+
+module TrailGuide
+  module Algorithms
+    def self.algorithm(algo)
+      case algo
+      when :weighted
+        algo = TrailGuide::Algorithms::Weighted
+      when :bandit
+        algo = TrailGuide::Algorithms::Bandit
+      when :distributed
+        algo = TrailGuide::Algorithms::Distributed
+      when :random
+        algo = TrailGuide::Algorithms::Random
+      else
+        algo = algo.constantize if algo.is_a?(String)
+      end
+      algo
+    end
+  end
+end

data/lib/trail_guide/catalog.rb

@@ -0,0 +1,71 @@
+module TrailGuide
+  class Catalog
+    include Enumerable
+
+    class << self
+      def catalog
+        @catalog ||= new
+      end
+
+      def register(klass)
+        catalog.register(klass)
+      end
+
+      def find(name)
+        catalog.find(name)
+      end
+
+      def select(name)
+        catalog.select(name)
+      end
+    end
+
+    attr_reader :experiments
+
+    def initialize(experiments=[])
+      @experiments = experiments
+    end
+
+    def each(&block)
+      experiments.each(&block)
+    end
+
+    def find(name)
+      if name.is_a?(Class)
+        experiments.find { |exp| exp == name }
+      else
+        experiments.find do |exp|
+          exp.experiment_name == name.to_s.underscore.to_sym ||
+            exp.metric == name.to_s.underscore.to_sym ||
+            exp.name == name.to_s.classify
+        end
+      end
+    end
+
+    def select(name)
+      if name.is_a?(Class)
+        experiments.select { |exp| exp == name }
+      else
+        experiments.select do |exp|
+          exp.experiment_name == name.to_s.underscore.to_sym ||
+            exp.metric == name.to_s.underscore.to_sym ||
+            exp.name == name.to_s.classify
+        end
+      end
+    end
+
+    def register(klass)
+      experiments << klass unless experiments.any? { |exp| exp == klass }
+      klass
+    end
+
+    def method_missing(meth, *args, &block)
+      return experiments.send(meth, *args, &block) if experiments.respond_to?(meth, true)
+      super
+    end
+
+    def respond_to_missing?(meth, include_private=false)
+      experiments.respond_to?(meth, include_private)
+    end
+  end
+end

data/lib/trail_guide/engine.rb

@@ -0,0 +1,65 @@
+module TrailGuide
+  class Engine < ::Rails::Engine
+    isolate_namespace TrailGuide
+
+    config.generators do |g|
+      g.test_framework = :rspec
+    end
+
+    initializer "trailguide" do |app|
+      TrailGuide::Engine.load_experiments
+      ActionController::Base.send :include, TrailGuide::Helper
+      ActionController::Base.helper TrailGuide::Helper
+    end
+
+    def self.load_experiments
+      # Load experiments from YAML configs if any exists
+      load_yaml_experiments(Rails.root.join("config/experiments.yml"))
+      Dir[Rails.root.join("config/experiments/**/*.yml")].each { |f| load_yaml_experiments(f) }
+
+      # Load experiments from ruby configs if any exist
+      DSL.instance_eval(File.read(Rails.root.join("config/experiments.rb"))) if File.exists?(Rails.root.join("config/experiments.rb"))
+      Dir[Rails.root.join("config/experiments/**/*.rb")].each { |f| DSL.instance_eval(File.read(f)) }
+
+      # Load any experiment classes defined in the app
+      Dir[Rails.root.join("app/experiments/**/*.rb")].each { |f| load f }
+    end
+
+    def self.load_yaml_experiments(file)
+      experiments = (YAML.load_file(file) || {} rescue {})
+        .symbolize_keys.map { |k,v| [k, v.symbolize_keys] }.to_h
+
+      experiments.each do |name, options|
+        expvars = options[:variants].map do |var|
+          if var.is_a?(Array)
+            [var[0], var[1].symbolize_keys]
+          else
+            [var]
+          end
+        end
+
+        DSL.experiment(name) do
+          expvars.each do |expvar|
+            variant *expvar
+          end
+          control                     options[:control] if options[:control]
+          algorithm                   options[:algorithm] if options[:algorithm]
+          goals                       options[:goals] if options[:goals]
+          metric                      options[:metric] if options[:metric]
+          resettable                  options[:resettable] if options.key?(:resettable)
+          allow_multiple_conversions  options[:allow_multiple_conversions] if options.key?(:allow_multiple_conversions)
+          allow_multiple_goals        options[:allow_multiple_goals] if options.key?(:allow_multiple_goals)
+        end
+      end
+    end
+
+    class DSL
+      def self.experiment(name, &block)
+        Class.new(TrailGuide::Experiment) do
+          experiment_name name
+          instance_eval &block
+        end
+      end
+    end
+  end
+end

data/lib/trail_guide/experiment.rb

@@ -0,0 +1,327 @@
+module TrailGuide
+  class Experiment
+    class << self
+      def inherited(child)
+        # TODO allow inheriting algo, variants, goals, metrics, etc.
+        TrailGuide::Catalog.register(child)
+      end
+
+      # TODO could probably move all this configuration stuff at the class level
+      # into a canfig object instead...?
+      def experiment_name(name=nil)
+        @experiment_name = name.to_s.underscore.to_sym unless name.nil?
+        @experiment_name || self.name.try(:underscore).try(:to_sym)
+      end
+
+      def config_algorithm
+        config_algo = TrailGuide.configuration.algorithm
+        case config_algo
+        when :weighted
+          config_algo = TrailGuide::Algorithms::Weighted
+        when :bandit
+          config_algo = TrailGuide::Algorithms::Bandit
+        when :distributed
+          config_algo = TrailGuide::Algorithms::Distributed
+        when :random
+          config_algo = TrailGuide::Algorithms::Random
+        else
+          config_algo = config_algo.constantize if config_algo.is_a?(String)
+        end
+        config_algo
+      end
+
+      def algorithm(algo=nil)
+        @algorithm = TrailGuide::Algorithms.algorithm(algo) unless algo.nil?
+        @algorithm ||= TrailGuide::Algorithms.algorithm(TrailGuide.configuration.algorithm)
+      end
+
+      def resettable(reset)
+        @resettable = reset
+      end
+
+      def resettable?
+        if @resettable.nil?
+          !TrailGuide.configuration.reset_manually
+        else
+          !!@resettable
+        end
+      end
+
+      def variant(name, metadata: {}, weight: 1, control: false)
+        raise ArgumentError, "The variant #{name} already exists in experiment #{experiment_name}" if variants.any? { |var| var == name }
+        control = true if variants.empty?
+        variant = Variant.new(self, name, metadata: metadata, weight: weight, control: control)
+        variants << variant
+        variant
+      end
+
+      def variants(include_control=true)
+        @variants ||= []
+        if include_control
+          @variants
+        else
+          @variants.select { |var| !var.control? }
+        end
+      end
+
+      def control(name=nil)
+        return variants.find { |var| var.control? } || variants.first if name.nil?
+
+        variants.each(&:variant!)
+        var_idx = variants.index { |var| var == name }
+
+        if var_idx.nil?
+          variant = Variant.new(self, name, control: true)
+        else
+          variant = variants.slice!(var_idx, 1)[0]
+          variant.control!
+        end
+
+        variants.unshift(variant)
+        return variant
+      end
+
+      def funnel(name)
+        funnels << name.to_s.underscore.to_sym
+      end
+      alias_method :goal, :funnel
+
+      def funnels(arr=nil)
+        @funnels = arr unless arr.nil?
+        @funnels ||= []
+      end
+      alias_method :goals, :funnels
+
+      def metric(key=nil)
+        @metric = key.to_s.underscore.to_sym unless key.nil?
+        @metric ||= experiment_name
+      end
+
+      def allow_multiple_conversions(allow)
+        @allow_multiple_conversions = allow
+      end
+
+      def allow_multiple_conversions?
+        !!@allow_multiple_conversions
+      end
+
+      def allow_multiple_goals(allow)
+        @allow_multiple_goals = allow
+      end
+
+      def allow_multiple_goals?
+        !!@allow_multiple_goals
+      end
+
+      def callbacks
+        @callbacks ||= begin
+          callbacks = {
+            on_choose:   [TrailGuide.configuration.on_experiment_choose].compact,
+            on_use:      [TrailGuide.configuration.on_experiment_use].compact,
+            on_convert:  [TrailGuide.configuration.on_experiment_convert].compact,
+            on_start:    [TrailGuide.configuration.on_experiment_start].compact,
+            on_stop:     [TrailGuide.configuration.on_experiment_stop].compact,
+            on_reset:    [TrailGuide.configuration.on_experiment_reset].compact,
+            on_delete:   [TrailGuide.configuration.on_experiment_delete].compact,
+          }
+        end
+      end
+
+      def on_choose(meth=nil, &block)
+        callbacks[:on_choose] << (meth || block)
+      end
+
+      def on_use(meth=nil, &block)
+        callbacks[:on_use] << (meth || block)
+      end
+
+      def on_convert(meth=nil, &block)
+        callbacks[:on_convert] << (meth || block)
+      end
+
+      def on_start(meth=nil, &block)
+        callbacks[:on_start] << (meth || block)
+      end
+
+      def on_stop(meth=nil, &block)
+        callbacks[:on_stop] << (meth || block)
+      end
+
+      def on_reset(meth=nil, &block)
+        callbacks[:on_reset] << (meth || block)
+      end
+
+      def on_delete(meth=nil, &block)
+        callbacks[:on_delete] << (meth || block)
+      end
+
+      def run_callbacks(hook, *args)
+        return unless callbacks[hook]
+        args.unshift(self)
+        callbacks[hook].each do |callback|
+          if callback.respond_to?(:call)
+            callback.call(*args)
+          else
+            send(callback, *args)
+          end
+        end
+      end
+
+      def start!
+        return false if started?
+        save! unless persisted?
+        started = TrailGuide.redis.hset(storage_key, 'started_at', Time.now.to_i)
+        run_callbacks(:on_start)
+        started
+      end
+
+      def stop!
+        return false unless started?
+        stopped = TrailGuide.redis.hdel(storage_key, 'started_at')
+        run_callbacks(:on_stop)
+        stopped
+      end
+
+      def started_at
+        started = TrailGuide.redis.hget(storage_key, 'started_at')
+        return Time.at(started.to_i) if started
+      end
+
+      def started?
+        !!started_at
+      end
+
+      def declare_winner!(variant)
+        variant = variant.name if variant.is_a?(Variant)
+        TrailGuide.redis.hset(storage_key, 'winner', variant.to_s.underscore)
+      end
+
+      def winner
+        winner = TrailGuide.redis.hget(storage_key, 'winner')
+        return variants.find { |var| var == winner } if winner
+      end
+
+      def winner?
+        !!winner
+      end
+
+      def persisted?
+        TrailGuide.redis.exists(storage_key)
+      end
+
+      def save!
+        variants.each(&:save!)
+        TrailGuide.redis.hsetnx(storage_key, 'name', experiment_name)
+      end
+
+      def delete!
+        variants.each(&:delete!)
+        deleted = TrailGuide.redis.del(storage_key)
+        run_callbacks(:on_delete)
+        deleted
+      end
+
+      def reset!
+        reset = (delete! && save!)
+        run_callbacks(:on_reset)
+        reset
+      end
+
+      def as_json(opts={})
+        # TODO fill in the rest of the values i've added
+        {
+          experiment_name: experiment_name,
+          algorithm: algorithm,
+          variants: variants.as_json
+        }
+      end
+
+      def storage_key
+        experiment_name
+      end
+    end
+
+    attr_reader :participant
+    delegate :experiment_name, :variants, :control, :funnels, :storage_key,
+      :started?, :started_at, :start!, :resettable?, :winner?, :winner,
+      :allow_multiple_conversions?, :allow_multiple_goals?, :callbacks,
+      to: :class
+
+    def initialize(participant)
+      @participant = participant
+    end
+
+    def algorithm
+      @algorithm ||= self.class.algorithm.new(self)
+    end
+
+    def choose!(metadata: nil, **opts)
+      return control if TrailGuide.configuration.disabled
+
+      variant = choose_variant!(metadata: metadata, **opts)
+      run_callbacks(:on_use, variant, metadata)
+      variant
+    end
+
+    def choose_variant!(override: nil, excluded: false, metadata: nil)
+      return control if TrailGuide.configuration.disabled
+      if override.present?
+        variant = variants.find { |var| var == override }
+        return variant unless TrailGuide.configuration.store_override && started?
+      else
+        return winner if winner?
+        return control if excluded
+        return control if !started? && TrailGuide.configuration.start_manually
+        start! unless started?
+        return variants.find { |var| var == participant[storage_key] } if participating?
+        return control unless TrailGuide.configuration.allow_multiple_experiments == true || !participant.participating_in_active_experiments?(TrailGuide.configuration.allow_multiple_experiments == false) 
+
+        variant = algorithm.choose!(metadata: metadata)
+      end
+
+      participant.participating!(variant)
+      variant.increment_participation!
+      run_callbacks(:on_choose, variant, metadata)
+      variant
+    end
+
+    def convert!(checkpoint=nil, metadata: nil)
+      return false unless participating?
+      raise ArgumentError, "You must provide a valid goal checkpoint for #{experiment_name}" unless checkpoint.present? || funnels.empty?
+      raise ArgumentError, "Unknown goal checkpoint: #{checkpoint}" unless checkpoint.nil? || funnels.any? { |funnel| funnel == checkpoint.to_s.underscore.to_sym }
+      # TODO eventually allow progressing through funnel checkpoints towards goals
+      if converted?(checkpoint)
+        return false unless allow_multiple_conversions?
+      elsif converted?
+        return false unless allow_multiple_goals?
+      end
+
+      variant = variants.find { |var| var == participant[storage_key] }
+      # TODO eventually only reset if we're at the final goal in a funnel
+      participant.converted!(variant, checkpoint, reset: resettable?)
+      variant.increment_conversion!(checkpoint)
+      run_callbacks(:on_convert, variant, checkpoint, metadata)
+      variant
+    end
+
+    def participating?
+      participant.participating?(self)
+    end
+
+    def converted?(checkpoint=nil)
+      participant.converted?(self, checkpoint)
+    end
+
+    def run_callbacks(hook, *args)
+      return unless callbacks[hook]
+      args.unshift(self)
+      callbacks[hook].each do |callback|
+        if callback.respond_to?(:call)
+          callback.call(*args)
+        else
+          send(callback, *args)
+        end
+      end
+    end
+  end
+end

data/lib/trail_guide/helper.rb

@@ -0,0 +1,185 @@
+module TrailGuide
+  module Helper
+    def trailguide(metric=nil, **opts, &block)
+      proxy = HelperProxy.new(self)
+      return proxy if metric.nil?
+      proxy.choose!(metric, **opts, &block)
+    end
+
+    class HelperProxy
+      attr_reader :context
+
+      def initialize(context, participant: nil)
+        @context = context
+        @participant = participant
+      end
+
+      def new(metric)
+        MetricProxy.new(context, metric, participant: participant)
+      end
+
+      def choose!(metric, **opts, &block)
+        new(metric).choose!(**opts, &block)
+      end
+
+      def run!(metric, **opts)
+        new(metric).run!(**opts)
+      end
+
+      def render!(metric, **opts)
+        new(metric).render!(**opts)
+      end
+
+      def convert!(metric, checkpoint=nil, **opts, &block)
+        new(metric).convert!(checkpoint, **opts, &block)
+      end
+
+      def participant
+        @participant ||= TrailGuide::Participant.new(context)
+      end
+
+      def context_type
+        if context.is_a?(ActionView::Context)
+          :template
+        elsif context.is_a?(ActionController::Base)
+          :controller
+        end
+      end
+    end
+
+    class MetricProxy < HelperProxy
+      attr_reader :metric
+
+      def initialize(context, metric, **opts)
+        super(context, **opts)
+        @metric = metric
+      end
+
+      def choose!(**opts, &block)
+        raise ArgumentError, "Please provide a single experiment" unless experiments.length == 1
+        opts = {override: override_variant, excluded: exclude_visitor?}.merge(opts)
+        variant = experiment.choose!(**opts)
+        if block_given?
+          yield variant, opts[:metadata]
+        else
+          variant
+        end
+      end
+
+      def run!(methods: nil, **opts)
+        raise ArgumentError, "Please provide a single experiment" unless experiments.length == 1
+        choose!(**opts) do |variant, metadata|
+          varmeth = methods[variant.name] if methods
+          varmeth ||= variant.name
+
+          unless context.respond_to?(varmeth, true)
+            if context_type == :controller
+              raise NoMethodError,
+                "You must define a controller method that matches variant `#{variant.name}` in your experiment `#{metric}`. In this case it looks like you need to define #{context.class.name}##{varmeth}(metadata={})"
+            elsif context_type == :template
+              raise NoMethodError,
+                "You must define a helper method that matches variant `#{variant.name}` in your experiment `#{metric}`. In this case it looks like you need to define ApplicationHelper##{varmeth}(metadata={})"
+            else
+              raise NoMethodError,
+                "You must define a method that matches variant `#{variant.name}` in your experiment `#{metric}`. In this case it looks like you need to define #{context.class.name}##{varmeth}(metadata={})"
+            end
+          end
+
+          arguments = context.method(varmeth).parameters
+          if arguments.empty?
+            context.send(varmeth)
+          elsif arguments.length > 1 || arguments[0][0] == :rest
+            context.send(varmeth, variant, **variant.metadata)
+          elsif arguments.length == 1
+            context.send(varmeth, **variant.metadata)
+          end
+        end
+      end
+
+      def render!(prefix: nil, templates: nil, **opts)
+        raise NoMethodError, "The current context does not support rendering. Rendering is only available for controllers and views." unless context.respond_to?(:render, true)
+        raise ArgumentError, "Please provide a single experiment" unless experiments.length == 1
+        choose!(**opts) do |variant, metadata|
+          locals = { variant: variant, metadata: variant.metadata }
+          locals = { locals: locals } if context_type == :controller
+
+          template = templates[variant.name] if templates
+          prefix ||= (context.try(:view_context) || context).lookup_context.prefixes.first + '/'
+          template ||= "#{prefix.to_s}#{variant.experiment.experiment_name.to_s.underscore}/#{variant.name.to_s.underscore}"
+
+          context.send(:render, template.to_s, **locals)
+        end
+      end
+
+      def convert!(checkpoint=nil, **opts, &block)
+        checkpoints = experiments.map { |experiment| experiment.convert!(checkpoint, **opts) }
+        return false unless checkpoints.any?
+        if block_given?
+          yield checkpoints, opts[:metadata]
+        else
+          checkpoints
+        end
+      end
+
+      def experiments
+        @experiments ||= TrailGuide::Catalog.select(metric).map do |experiment|
+          experiment.new(participant)
+        end
+      end
+
+      def experiment
+        @experiment ||= experiments.first
+      end
+
+      def override_variant
+        return unless context.respond_to?(:params, true)
+        params = context.send(:params)
+        return unless params.key?(TrailGuide.configuration.override_parameter)
+        experiment_params = params[TrailGuide.configuration.override_parameter]
+        return unless experiment_params.key?(experiment.experiment_name.to_s)
+        varname = experiment_params[experiment.experiment_name.to_s]
+        variant = experiment.variants.find { |var| var == varname }
+        variant.try(:name)
+      end
+
+      def exclude_visitor?
+        instance_exec(context, &TrailGuide.configuration.request_filter)
+      end
+
+      def is_preview?
+        return false unless context.respond_to?(:request, true)
+        headers = context.send(:request).try(:headers)
+        headers && headers['x-purpose'] == 'preview'
+      end
+
+      def is_filtered_user_agent?
+        return false if TrailGuide.configuration.filtered_user_agents.empty?
+        return false unless context.respond_to?(:request, true)
+        request = context.send(:request)
+        return false unless request && request.user_agent
+
+        TrailGuide.configuration.filtered_user_agents do |ua|
+          return true if ua.class == String && request.user_agent == ua
+          return true if ua.class == Regexp && request.user_agent =~ ua
+        end
+
+        return false
+      end
+
+      def is_filtered_ip_address?
+        return false if TrailGuide.configuration.filtered_ip_addresses.empty?
+        return false unless context.respond_to?(:request, true)
+        request = context.send(:request)
+        return false unless request && request.ip
+
+        TrailGuide.configuration.filtered_ip_addresses.each do |ip|
+          return true if ip.class == String && request.ip == ip
+          return true if ip.class == Regexp && request.ip =~ ip
+          return true if ip.class == Range && ip.first.class == IPAddr && ip.include?(IPAddr.new(request.ip))
+        end
+
+        return false
+      end
+    end
+  end
+end