trailguide 0.2.1 → 0.3.0

data/lib/trail_guide/adapters.rb

@@ -1,3 +1,5 @@
+require "trail_guide/adapters/experiments"
+require "trail_guide/adapters/variants"
 require "trail_guide/adapters/participants"
 
 module TrailGuide

data/lib/trail_guide/adapters/experiments.rb

@@ -0,0 +1,8 @@
+require 'trail_guide/adapters/experiments/redis'
+
+module TrailGuide
+  module Adapters
+    module Experiments
+    end
+  end
+end

data/lib/trail_guide/adapters/experiments/redis.rb

@@ -0,0 +1,48 @@
+module TrailGuide
+  module Adapters
+    module Experiments
+      class Redis
+        attr_reader :experiment
+        delegate :storage_key, to: :experiment
+
+        def initialize(experiment, redis: nil)
+          @experiment = experiment
+          @redis = redis
+        end
+
+        def redis
+          @redis ||= TrailGuide.redis
+        end
+
+        def get(attr)
+          redis.hget(storage_key, attr.to_s)
+        end
+
+        def set(attr, val)
+          redis.hset(storage_key, attr.to_s, val.to_s)
+          val.to_s
+        end
+
+        def setnx(attr, val)
+          val.to_s if redis.hsetnx(storage_key, attr.to_s, val.to_s)
+        end
+
+        def delete(attr)
+          redis.hdel(storage_key, attr.to_s)
+        end
+
+        def exists?(attr)
+          redis.hexists(storage_key, attr.to_s)
+        end
+
+        def persisted?
+          redis.exists(storage_key)
+        end
+
+        def destroy
+          redis.del(storage_key)
+        end
+      end
+    end
+  end
+end

data/lib/trail_guide/adapters/participants/cookie.rb

@@ -35,6 +35,7 @@ module TrailGuide
           end
 
           def destroy!
+            @cookie = nil
             cookies.delete(config.cookie.to_s)
           end
 

data/lib/trail_guide/adapters/participants/unity.rb

@@ -8,6 +8,10 @@ module TrailGuide
 
         def initialize(&block)
           configure do |config|
+            # TODO make visitor/user configuration more flexible, allow stuff like:
+            #
+            # config.visitor = -> (context) { context.cookies['visitor_id'] }
+            # config.user =    -> (context) { context.current_user.try(:id) }
             config.visitor_cookie = nil
             config.user_id_key = :id
 
@@ -17,6 +21,7 @@ module TrailGuide
               config.expiration = 1.year.seconds
             end
 
+            # TODO use cookie or session adapter by default instead?
             config.visitor_adapter = TrailGuide::Adapters::Participants::Redis.configure do |config|
               config.namespace = 'unity:visitors'
               config.lookup = -> (visitor_id) { visitor_id }
@@ -43,7 +48,7 @@ module TrailGuide
           end
 
           if logged_out_context?
-            unity.visitor_id ||= context.send(:cookies)[configuration.visitor_cookie].gsub(/(%22|")/, '')
+            unity.visitor_id ||= context.send(:cookies)[configuration.visitor_cookie]
           end
 
           unity.sync!
@@ -57,9 +62,12 @@ module TrailGuide
           end
         end
 
+        # TODO introduce Unity::Adapter class, which wraps BOTH/ALL of the configured adapters (either anonymous, visitor, user, or visitor+user) to keep everything in sync between them
+
         protected
 
         def context_type
+          # TODO allow a configuration.preference when both visitor and user context are available?
           if visitor_context?
             return :visitor
           end

data/lib/trail_guide/adapters/variants.rb

@@ -0,0 +1,8 @@
+require 'trail_guide/adapters/variants/redis'
+
+module TrailGuide
+  module Adapters
+    module Variants
+    end
+  end
+end

data/lib/trail_guide/adapters/variants/redis.rb

@@ -0,0 +1,52 @@
+module TrailGuide
+  module Adapters
+    module Variants
+      class Redis
+        attr_reader :variant
+        delegate :storage_key, to: :variant
+
+        def initialize(variant, redis: nil)
+          @variant = variant
+          @redis = redis
+        end
+
+        def redis
+          @redis ||= TrailGuide.redis
+        end
+
+        def get(attr)
+          redis.hget(storage_key, attr.to_s)
+        end
+
+        def set(attr, val)
+          redis.hset(storage_key, attr.to_s, val.to_s)
+          val.to_s
+        end
+
+        def setnx(attr, val)
+          val.to_s if redis.hsetnx(storage_key, attr.to_s, val.to_s)
+        end
+
+        def increment(attr, cnt=1)
+          redis.hincrby(storage_key, attr.to_s, cnt)
+        end
+
+        def delete(attr)
+          redis.hdel(storage_key, attr.to_s)
+        end
+
+        def exists?(attr)
+          redis.hexists(storage_key, attr.to_s)
+        end
+
+        def persisted?
+          redis.exists(storage_key)
+        end
+
+        def destroy
+          redis.del(storage_key)
+        end
+      end
+    end
+  end
+end

data/lib/trail_guide/admin/engine.rb

@@ -8,6 +8,7 @@ module TrailGuide
       end
 
       paths["config/routes.rb"] = "config/routes/admin.rb"
+      paths["config/initializers"] = ["config/initializers/admin.rb", "config/initializers/assets.rb"]
     end
   end
 end

data/lib/trail_guide/algorithms.rb

@@ -1,7 +1,9 @@
+require "trail_guide/algorithms/algorithm"
 require "trail_guide/algorithms/weighted"
 require "trail_guide/algorithms/distributed"
 require "trail_guide/algorithms/bandit"
 require "trail_guide/algorithms/random"
+require "trail_guide/algorithms/static"
 
 module TrailGuide
   module Algorithms
@@ -15,6 +17,8 @@ module TrailGuide
         algo = TrailGuide::Algorithms::Distributed
       when :random
         algo = TrailGuide::Algorithms::Random
+      when :static
+        algo = TrailGuide::Algorithms::Static
       else
         algo = algo.constantize if algo.is_a?(String)
       end

data/lib/trail_guide/algorithms/algorithm.rb

@@ -0,0 +1,29 @@
+module TrailGuide
+  module Algorithms
+    class Algorithm
+      attr_reader :experiment
+
+      def self.choose!(experiment, **opts)
+        new(experiment).choose!(**opts)
+      end
+
+      def initialize(experiment)
+        @experiment = experiment
+      end
+
+      def choose!(**opts)
+        raise NotImplementedError, 'You must define a `#choose!(**opts)` method for your algorithm'
+      end
+
+      protected
+
+      def control
+        experiment.control
+      end
+
+      def variants
+        experiment.variants
+      end
+    end
+  end
+end

data/lib/trail_guide/algorithms/bandit.rb

@@ -2,32 +2,23 @@ require 'simple-random'
 
 module TrailGuide
   module Algorithms
-    class Bandit
-      attr_reader :experiment
-
-      def self.choose!(experiment, **opts)
-        new(experiment).choose!(**opts)
-      end
-
-      def initialize(experiment)
-        @experiment = experiment
-      end
-
+    class Bandit < Algorithm
       def choose!(**opts)
-        guess = best_guess
-        experiment.variants.find { |var| var == guess }
+        variants.find { |var| var == best_guess }
       end
 
       private
 
+      def guesses
+        @guesses ||= variants.map do |variant|
+          [variant.name, arm_guess(variant.participants, variant.converted)]
+        end.to_h
+      end
+
       def best_guess
         @best_guess ||= begin
-          guesses = {}
-          experiment.variants.each do |variant|
-            guesses[variant.name] = arm_guess(variant.participants, variant.converted)
-          end
           gmax = guesses.values.max
-          best = guesses.keys.select { |name| guesses[name] ==  gmax }
+          best = guesses.keys.select { |name| guesses[name] == gmax }
           best.sample
         end
       end

data/lib/trail_guide/algorithms/distributed.rb

@@ -1,25 +1,18 @@
 module TrailGuide
   module Algorithms
-    class Distributed
-      attr_reader :experiment
-
-      def self.choose!(experiment, **opts)
-        new(experiment).choose!(**opts)
-      end
-
-      def initialize(experiment)
-        @experiment = experiment
-      end
-
+    class Distributed < Algorithm
       def choose!(**opts)
-        variants.sample
+        options.sample
       end
 
       private
 
-      def variants
-        groups = experiment.variants.group_by(&:participants)
-        groups.min_by { |c,g| c }.last
+      def grouped
+        @grouped ||= variants.group_by(&:participants)
+      end
+
+      def options
+        @options ||= grouped.min_by { |c,g| c }.last
       end
     end
   end

data/lib/trail_guide/algorithms/random.rb

@@ -1,18 +1,8 @@
 module TrailGuide
   module Algorithms
-    class Random
-      attr_reader :experiment
-
-      def self.choose!(experiment, **opts)
-        new(experiment).choose!(**opts)
-      end
-
-      def initialize(experiment)
-        @experiment = experiment
-      end
-
+    class Random < Algorithm
       def choose!(**opts)
-        experiment.variants.sample
+        variants.sample
       end
     end
   end

data/lib/trail_guide/algorithms/static.rb

@@ -0,0 +1,34 @@
+module TrailGuide
+  module Algorithms
+    class Static < Algorithm
+      def self.choose!(experiment, metadata: nil, &block)
+        new(experiment, &block).choose!(metadata: metadata)
+      end
+
+      def initialize(experiment=nil, &block)
+        raise ArgumentError, 'You must provide a comparison block when using the static algorithm' unless block_given?
+        @block = block
+        super(experiment)
+      end
+
+      def new(experiment)
+        TrailGuide.logger.warn "WARNING: Using the Static algorithm for an experiment which is configured with sticky_assignment. You should either use a different algorithm or configure sticky_assignment for the `#{experiment.experiment_name}` experiment." if experiment.configuration.sticky_assignment?
+        self.class.new(experiment, &@block)
+      end
+
+      def choose!(metadata: nil)
+        return control unless metadata.present?
+
+        variant = variants.find do |variant|
+          @block.call(variant.metadata, metadata)
+        end
+        
+        variant || control
+      rescue => e
+        TrailGuide.logger.error "#{e.class.name}: #{e.message}"
+        TrailGuide.logger.error e.backtrace.first
+        control
+      end
+    end
+  end
+end

data/lib/trail_guide/algorithms/weighted.rb

@@ -1,23 +1,11 @@
 module TrailGuide
   module Algorithms
-    class Weighted
-      attr_reader :experiment
-
-      def self.choose!(experiment, **opts)
-        new(experiment).choose!(**opts)
-      end
-
-      def initialize(experiment)
-        @experiment = experiment
-      end
-
+    class Weighted < Algorithm
       def choose!(**opts)
-        weights   = experiment.variants.map(&:weight)
-        reference = rand * weights.inject(:+)
-
-        experiment.variants.zip(weights).each do |variant,weight|
-          return variant if weight >= reference
-          reference -= weight
+        reference = rand * variants.sum(&:weight)
+        variants.each do |variant|
+          return variant if variant.weight >= reference
+          reference -= variant.weight
         end
       end
     end

data/lib/trail_guide/catalog.rb

@@ -7,19 +7,23 @@ module TrailGuide
         @catalog ||= new
       end
 
-      def load_experiments!
+      def load_experiments!(configs: [], classes: [])
         @catalog = nil
 
         # 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) }
+        [configs].flatten.each do |path|
+          Dir[Rails.root.join(path)].each { |f| load_yaml_experiments(f) if ['.yml', '.yaml'].include?(File.extname(f)) }
+        end
 
         # 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)) }
+        [configs].flatten.each do |path|
+          Dir[Rails.root.join(path)].each { |f| DSL.instance_eval(File.read(f)) if File.extname(f) == '.rb' }
+        end
 
         # Load any experiment classes defined in the app
-        Dir[Rails.root.join("app/experiments/**/*.rb")].each { |f| load f }
+        [classes].flatten.each do |path|
+          Dir[Rails.root.join(path)].each { |f| load f }
+        end
       end
 
       def load_yaml_experiments(file)
@@ -46,7 +50,7 @@ module TrailGuide
 
             expgoals.each do |expgoal|
               goal expgoal
-            end
+            end if expgoals.present?
 
             config.control                    = options[:control] if options[:control]
             config.groups                     = options[:groups] if options[:groups]
@@ -76,15 +80,24 @@ module TrailGuide
       end
     end
 
-    delegate :combined_experiment, to: :class
-    attr_reader :experiments
+    attr_reader :experiments, :combined
+    delegate :new, to: :class
+    delegate :each, to: :experiments
 
-    def initialize(experiments=[])
+    def initialize(experiments=[], combined=[])
       @experiments = experiments
+      @combined = combined
     end
 
-    def each(&block)
-      experiments.each(&block)
+    def combined_experiment(exp, name)
+      combo = @combined.find do |cex|
+        cex.experiment_name == name.to_s.underscore.to_sym &&
+        cex.parent.experiment_name == exp.experiment_name
+      end
+      return combo if combo.present?
+      combo = self.class.combined_experiment(exp, name)
+      @combined << combo
+      combo
     end
 
     def groups
@@ -100,47 +113,49 @@ module TrailGuide
         end
       end.flatten
 
-      self.class.new(exploded)
+      new(exploded, @combined)
     end
 
     def calibrating
-      self.class.new(to_a.select(&:calibrating?))
+      new(to_a.select(&:calibrating?), @combined)
     end
 
     def started
-      self.class.new(to_a.select { |e| e.started? && !e.winner? })
+      new(to_a.select { |e| e.started? && !e.winner? }, @combined)
     end
 
     def scheduled
-      self.class.new(to_a.select { |e| e.scheduled? && !e.winner? })
+      new(to_a.select { |e| e.scheduled? && !e.winner? }, @combined)
     end
 
     def running
-      self.class.new(to_a.select { |e| e.running? && !e.winner? })
+      new(to_a.select { |e| e.running? && !e.winner? }, @combined)
     end
 
     def paused
-      self.class.new(to_a.select { |e| e.paused? && !e.winner? })
+      new(to_a.select { |e| e.paused? && !e.winner? }, @combined)
     end
 
     def stopped
-      self.class.new(to_a.select { |e| e.stopped? && !e.winner? })
+      new(to_a.select { |e| e.stopped? && !e.winner? }, @combined)
     end
 
     def ended
-      self.class.new(to_a.select(&:winner?))
+      new(to_a.select(&:winner?), @combined)
     end
 
     def unstarted
-      self.class.new(to_a.select { |e| !e.started? && !e.calibrating? && !e.scheduled? && !e.winner? })
+      new(to_a.select { |e| !e.started? && !e.calibrating? && !e.scheduled? && !e.winner? }, @combined)
     end
 
     def not_running
-      self.class.new(to_a.select { |e| !e.running? })
+      new(to_a.select { |e| !e.running? }, @combined)
     end
 
     def by_started
       scoped = to_a.sort do |a,b|
+        # TODO finish implementing specs, then implement `experiment.fresh?`, then (maybe) re-work this all
+        # into an experiment spaceship operator
         if !(a.started? || a.scheduled? || a.winner?) && !(b.started? || b.scheduled? || b.winner?)
           a.experiment_name.to_s <=> b.experiment_name.to_s
         elsif !(a.started? || a.scheduled? || a.winner?)
@@ -159,32 +174,48 @@ module TrailGuide
           elsif !a.running? && b.running?
             1
           elsif a.running? && b.running?
-            a.started_at <=> b.started_at
+            if a.started_at == b.started_at
+              a.experiment_name.to_s <=> b.experiment_name.to_s
+            else
+              a.started_at <=> b.started_at
+            end
           elsif a.paused? && !b.paused?
             -1
           elsif !a.paused? && b.paused?
             1
           elsif a.paused? && b.paused?
-            a.paused_at <=> b.paused_at
+            if a.paused_at == b.paused_at
+              a.experiment_name.to_s <=> b.experiment_name.to_s
+            else
+              a.paused_at <=> b.paused_at
+            end
           elsif a.scheduled? && !b.scheduled?
             -1
           elsif !a.scheduled? && b.scheduled?
             1
           elsif a.scheduled? && b.scheduled?
-            a.started_at <=> b.started_at
+            if a.started_at == b.started_at
+              a.experiment_name.to_s <=> b.experiment_name.to_s
+            else
+              a.started_at <=> b.started_at
+            end
           elsif a.stopped? && !b.stopped?
-            -1
+            -1 # TODO remove unused case
           elsif !a.stopped? && b.stopped?
-            1
+            1 # TODO remove unused case
           elsif a.stopped? && b.stopped?
-            a.stopped_at <=> b.stopped_at
+            if a.stopped_at == b.stopped_at
+              a.experiment_name.to_s <=> b.experiment_name.to_s
+            else
+              a.stopped_at <=> b.stopped_at
+            end
           else
             a.experiment_name.to_s <=> b.experiment_name.to_s
           end
         end
       end
 
-      self.class.new(scoped)
+      new(scoped, @combined)
     end
 
     def find(name)
@@ -227,7 +258,7 @@ module TrailGuide
         end
       end
 
-      self.class.new(selected)
+      new(selected, @combined)
     end
 
     def register(klass)
@@ -235,8 +266,13 @@ module TrailGuide
       klass
     end
 
-    def deregister(key)
-      # TODO (mostly only useful for engine specs)
+    def deregister(key, remove_const=false)
+      klass = find(key)
+      return unless klass.present?
+      experiments.delete(klass)
+      return klass unless remove_const && klass.name.present?
+      Object.send(:remove_const, :"#{klass.name}")
+      return key
     end
 
     def export
@@ -256,9 +292,9 @@ module TrailGuide
 
         experiment.reset!
         TrailGuide.redis.hsetnx(experiment.storage_key, 'name', experiment.experiment_name)
-        TrailGuide.redis.hset(experiment.storage_key, 'started_at', est['started_at']) if est['started_at'].present?
-        TrailGuide.redis.hset(experiment.storage_key, 'paused_at', est['paused_at']) if est['paused_at'].present?
-        TrailGuide.redis.hset(experiment.storage_key, 'stopped_at', est['stopped_at']) if est['stopped_at'].present?
+        TrailGuide.redis.hset(experiment.storage_key, 'started_at', DateTime.parse(est['started_at']).to_i) if est['started_at'].present?
+        TrailGuide.redis.hset(experiment.storage_key, 'paused_at', DateTime.parse(est['paused_at']).to_i) if est['paused_at'].present?
+        TrailGuide.redis.hset(experiment.storage_key, 'stopped_at', DateTime.parse(est['stopped_at']).to_i) if est['stopped_at'].present?
         TrailGuide.redis.hset(experiment.storage_key, 'winner', est['winner']) if est['winner'].present?
 
         est['variants'].each do |var,vst|
@@ -277,6 +313,13 @@ module TrailGuide
       end
     end
 
+    def missing
+      TrailGuide.redis.keys.select do |key|
+        exp = key.split(':').first
+        find(exp).nil?
+      end
+    end
+
     def orphaned(key, trace)
       added = TrailGuide.redis.sadd("orphans:#{key}", trace)
       TrailGuide.redis.expire("orphans:#{key}", 15.minutes.seconds)
@@ -319,6 +362,7 @@ module TrailGuide
     end
   end
 
+  # TrailGuide.catalog
   def self.catalog
     TrailGuide::Catalog.catalog
   end