trailguide 0.2.1 → 0.3.0

data/lib/trail_guide/config.rb

@@ -13,10 +13,8 @@ module TrailGuide
       super(*args, **opts, &block)
     end
 
-    def configure(*args, &block)
-      super(*args) do |config|
-        yield(config, TrailGuide::Experiment.configuration) if block_given?
-      end
+    def paths
+      @paths ||= Struct.new(:configs, :classes).new([],[])
     end
 
     def redis

data/lib/trail_guide/engine.rb

@@ -7,9 +7,10 @@ module TrailGuide
     end
 
     paths["config/routes.rb"] = "config/routes/engine.rb"
+    paths["config/initializers"] = ["config/initializers/trailguide.rb", "config/initializers/experiment.rb"]
 
     initializer "trailguide" do |app|
-      TrailGuide::Catalog.load_experiments!
+      TrailGuide::Catalog.load_experiments!(**TrailGuide.configuration.paths.to_h)
       if TrailGuide.configuration.include_helpers
         ActionController::Base.send :include, TrailGuide::Helper
         ActionController::Base.helper TrailGuide::Helper

data/lib/trail_guide/experiments/base.rb

@@ -23,6 +23,11 @@ module TrailGuide
           configuration.configure(*args, &block)
         end
 
+        def adapter
+          @adapter ||= TrailGuide::Adapters::Experiments::Redis.new(self)
+        end
+
+        # TODO alias name once specs have solid coverage
         def experiment_name
           configuration.name
         end
@@ -45,7 +50,7 @@ module TrailGuide
 
         def run_callbacks(hook, *args)
           return unless callbacks[hook]
-          return args[0] if hook == :rollout_winner
+          return args[0] if hook == :rollout_winner # TODO do we need to account for this case here at the class level?
           args.unshift(self)
           callbacks[hook].each do |callback|
             if callback.respond_to?(:call)
@@ -59,7 +64,7 @@ module TrailGuide
         def start!(context=nil)
           return false if started?
           save! unless persisted?
-          started = TrailGuide.redis.hset(storage_key, 'started_at', Time.now.to_i)
+          started = adapter.set(:started_at, Time.now.to_i)
           run_callbacks(:on_start, context)
           started
         end
@@ -67,45 +72,45 @@ module TrailGuide
         def schedule!(start_at, stop_at=nil, context=nil)
           return false if started?
           save! unless persisted?
-          scheduled = TrailGuide.redis.hset(storage_key, 'started_at', start_at.to_i)
-          TrailGuide.redis.hset(storage_key, 'stopped_at', stop_at.to_i) if stop_at
+          scheduled = adapter.set(:started_at, start_at.to_i)
+          adapter.set(:stopped_at, stop_at.to_i) if stop_at
           run_callbacks(:on_schedule, start_at, stop_at, context)
           scheduled
         end
 
         def pause!(context=nil)
           return false unless running? && configuration.can_resume?
-          paused = TrailGuide.redis.hset(storage_key, 'paused_at', Time.now.to_i)
+          paused = adapter.set(:paused_at, Time.now.to_i)
           run_callbacks(:on_pause, context)
           paused
         end
 
         def stop!(context=nil)
           return false unless started? && !stopped?
-          stopped = TrailGuide.redis.hset(storage_key, 'stopped_at', Time.now.to_i)
+          stopped = adapter.set(:stopped_at, Time.now.to_i)
           run_callbacks(:on_stop, context)
           stopped
         end
 
         def resume!(context=nil)
           return false unless paused? && configuration.can_resume?
-          resumed = TrailGuide.redis.hdel(storage_key, 'paused_at')
+          resumed = adapter.delete(:paused_at)
           run_callbacks(:on_resume, context)
-          resumed
+          !!resumed
         end
 
         def started_at
-          started = TrailGuide.redis.hget(storage_key, 'started_at')
+          started = adapter.get(:started_at)
           return Time.at(started.to_i) if started
         end
 
         def paused_at
-          paused = TrailGuide.redis.hget(storage_key, 'paused_at')
+          paused = adapter.get(:paused_at)
           return Time.at(paused.to_i) if paused
         end
 
         def stopped_at
-          stopped = TrailGuide.redis.hget(storage_key, 'stopped_at')
+          stopped = adapter.get(:stopped_at)
           return Time.at(stopped.to_i) if stopped
         end
 
@@ -137,18 +142,24 @@ module TrailGuide
           enable_calibration? && start_manually? && !started?
         end
 
+        def fresh?
+          !started? && !scheduled? && !winner?
+        end
+
         def declare_winner!(variant, context=nil)
           variant = variants.find { |var| var == variant } unless variant.is_a?(Variant)
+          return false unless variant.present? && variant.experiment == self
           run_callbacks(:on_winner, variant, context)
-          TrailGuide.redis.hset(storage_key, 'winner', variant.name.to_s.underscore)
+          adapter.set(:winner, variant.name)
+          variant
         end
 
         def clear_winner!
-          TrailGuide.redis.hdel(storage_key, 'winner')
+          adapter.delete(:winner)
         end
 
         def winner
-          winner = TrailGuide.redis.hget(storage_key, 'winner')
+          winner = adapter.get(:winner)
           return variants.find { |var| var == winner } if winner
         end
 
@@ -156,32 +167,33 @@ module TrailGuide
           if combined?
             combined.all? { |combo| TrailGuide.catalog.find(combo).winner? }
           else
-            TrailGuide.redis.hexists(storage_key, 'winner')
+            adapter.exists?(:winner)
           end
         end
 
         def persisted?
-          TrailGuide.redis.exists(storage_key)
+          adapter.persisted?
         end
 
         def save!
-          combined.each { |combo| TrailGuide.catalog.find(combo).save! }
+          combined_experiments.each(&:save!)
           variants.each(&:save!)
-          TrailGuide.redis.hsetnx(storage_key, 'name', experiment_name)
+          adapter.setnx(:name, experiment_name)
         end
 
         def delete!(context=nil)
           combined.each { |combo| TrailGuide.catalog.find(combo).delete! }
           variants.each(&:delete!)
-          deleted = TrailGuide.redis.del(storage_key)
+          deleted = adapter.destroy
           run_callbacks(:on_delete, context)
-          deleted
+          true
         end
 
         def reset!(context=nil)
-          reset = (delete! && save!)
+          delete!(context)
+          save!
           run_callbacks(:on_reset, context)
-          reset
+          true
         end
 
         def participants
@@ -233,7 +245,8 @@ module TrailGuide
       end
 
       def winning_variant
-        run_callbacks(:rollout_winner, self.class.winner, participant)
+        return nil unless winner?
+        run_callbacks(:rollout_winner, winner, participant)
       end
 
       def choose!(override: nil, metadata: nil, **opts)
@@ -293,7 +306,10 @@ module TrailGuide
         start! unless started? || scheduled?
         return control unless running?
 
-        if participant.participating?
+        # only re-use the variant for experiments that store participation,
+        # all other (i.e. content-based) experiments should re-select and
+        # re-assign on enrollment
+        if configuration.sticky_assignment? && participant.participating?
           variant = participant.variant
           participant.participating!(variant)
           return variant
@@ -369,6 +385,7 @@ module TrailGuide
       def allow_conversion?(variant, checkpoint=nil, metadata=nil)
         if checkpoint.nil?
           return true if callbacks[:allow_conversion].empty?
+          # TODO why pass checkpoint through here if checkpoints are handled by their own method? it will always be nil here given current logic
           run_callbacks(:allow_conversion, true, checkpoint, variant, participant, metadata)
         else
           checkpoint.allow_conversion?(self, variant, metadata)

data/lib/trail_guide/experiments/combined_config.rb

@@ -7,6 +7,10 @@ module TrailGuide
         args.push(:parent)
         super(experiment, *args, **opts, &block)
       end
+
+      def parent
+        self[:parent]
+      end
     end
   end
 end

data/lib/trail_guide/experiments/config.rb

@@ -3,7 +3,7 @@ module TrailGuide
     class Config < Canfig::Config
       DEFAULT_KEYS = [
         :name, :summary, :preview_url, :algorithm, :groups, :variants, :goals,
-        :start_manually, :reset_manually, :store_participation, :store_override,
+        :start_manually, :reset_manually, :sticky_assignment, :store_override,
         :track_override, :combined, :allow_multiple_conversions,
         :allow_multiple_goals, :track_winner_conversions, :skip_request_filter,
         :target_sample_size, :can_resume, :enable_calibration
@@ -36,7 +36,7 @@ module TrailGuide
 
       def initialize(experiment, *args, **opts, &block)
         @experiment = experiment
-        opts = opts.merge(default_config)
+        opts = default_config.merge(opts)
         ancestor = opts.delete(:inherit)
         if ancestor.present?
           keys = opts.keys.dup.concat(args).concat(DEFAULT_KEYS).concat(CALLBACK_KEYS).uniq
@@ -58,8 +58,8 @@ module TrailGuide
         !!reset_manually
       end
 
-      def store_participation?
-        !!store_participation
+      def sticky_assignment?
+        !!sticky_assignment
       end
 
       def allow_multiple_conversions?
@@ -90,33 +90,16 @@ module TrailGuide
         @name ||= (self[:name] || experiment.name).try(:to_s).try(:underscore).try(:to_sym)
       end
 
-      def groups(*grps)
-        self[:groups] ||= []
-        unless grps.empty?
-          self[:groups] = self[:groups].concat([grps].flatten.map { |g| g.to_s.underscore.to_sym })
-        end
-        self[:groups]
-      end
-
-      def groups=(*grps)
-        self[:groups] = [grps].flatten.map { |g| g.to_s.underscore.to_sym }
-      end
-
-      def group(grp=nil)
-        unless grp.nil?
-          groups << grp.to_s.underscore.to_sym
-          return groups.last
+      def algorithm
+        if self[:algorithm].is_a?(Array) && self[:algorithm].last.respond_to?(:call)
+          @algorithm ||= TrailGuide::Algorithms.algorithm(self[:algorithm].first).new(&self[:algorithm].last)
+        else
+          @algorithm ||= TrailGuide::Algorithms.algorithm(self[:algorithm])
         end
-        groups.first
       end
 
-      def group=(grp)
-        groups.unshift(grp.to_s.underscore.to_sym)
-        groups.first
-      end
-
-      def algorithm
-        @algorithm ||= TrailGuide::Algorithms.algorithm(self[:algorithm])
+      def variants
+        self[:variants]
       end
 
       def variant(varname, metadata: {}, weight: 1, control: false)
@@ -147,6 +130,32 @@ module TrailGuide
         variant
       end
 
+      def groups(*grps)
+        self[:groups] ||= []
+        self[:groups] = self[:groups].map { |g| g.to_s.underscore.to_sym }
+        unless grps.empty?
+          self[:groups] = self[:groups].concat([grps].flatten.map { |g| g.to_s.underscore.to_sym })
+        end
+        self[:groups]
+      end
+
+      def groups=(*grps)
+        self[:groups] = [grps].flatten.map { |g| g.to_s.underscore.to_sym }
+      end
+
+      def group(grp=nil)
+        unless grp.nil?
+          groups << grp.to_s.underscore.to_sym
+          return groups.last
+        end
+        groups.first
+      end
+
+      def group=(grp)
+        groups.unshift(grp.to_s.underscore.to_sym)
+        groups.first
+      end
+
       def goal(name, **config, &block)
         goals << Metrics::Goal.new(experiment, name, **config, &block)
       end
@@ -164,6 +173,7 @@ module TrailGuide
 
       def goals(*names, **config, &block)
         self[:goals] ||= []
+        self[:goals] = self[:goals].map { |g| g.is_a?(Metrics::Goal) ? g : Metrics::Goal.new(experiment, g) }
         unless names.empty?
           self[:goals] = self[:goals].concat([names].flatten.map { |g| Metrics::Goal.new(experiment, g, **config, &block) })
         end
@@ -187,8 +197,12 @@ module TrailGuide
       end
 
       def metrics=(*names)
-        self.groups = *names
-        self.goals = *names
+        self.send(:groups=, *names.flatten)
+        self.send(:goals=, *names.flatten)
+      end
+
+      def combined
+        self[:combined]
       end
 
       def combined?
@@ -204,76 +218,91 @@ module TrailGuide
       end
 
       def on_choose(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_choose] ||= []
         self[:on_choose] << (meth || block)
       end
 
       def on_use(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_use] ||= []
         self[:on_use] << (meth || block)
       end
 
       def on_convert(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_convert] ||= []
         self[:on_convert] << (meth || block)
       end
 
       def on_start(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_start] ||= []
         self[:on_start] << (meth || block)
       end
 
       def on_schedule(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_schedule] ||= []
         self[:on_schedule] << (meth || block)
       end
 
       def on_stop(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_stop] ||= []
         self[:on_stop] << (meth || block)
       end
 
       def on_pause(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_pause] ||= []
         self[:on_pause] << (meth || block)
       end
 
       def on_resume(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_resume] ||= []
         self[:on_resume] << (meth || block)
       end
 
       def on_winner(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_winner] ||= []
         self[:on_winner] << (meth || block)
       end
 
       def on_reset(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_reset] ||= []
         self[:on_reset] << (meth || block)
       end
 
       def on_delete(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_delete] ||= []
         self[:on_delete] << (meth || block)
       end
 
       def on_redis_failover(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:on_redis_failover] ||= []
         self[:on_redis_failover] << (meth || block)
       end
 
       def allow_participation(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:allow_participation] ||= []
         self[:allow_participation] << (meth || block)
       end
 
       def allow_conversion(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:allow_conversion] ||= []
         self[:allow_conversion] << (meth || block)
       end
 
       def rollout_winner(meth=nil, &block)
+        raise ArgumentError if meth.nil? && !block_given?
         self[:rollout_winner] ||= []
         self[:rollout_winner] << (meth || block)
       end

data/lib/trail_guide/experiments/participant.rb

@@ -15,12 +15,14 @@ module TrailGuide
       def participating!(variant)
         @participating = true
         @variant = variant
-        participant.participating!(variant) if experiment.configuration.store_participation?
+        participant.participating!(variant) if experiment.configuration.sticky_assignment?
       end
 
       def converted?(checkpoint=nil)
         @converted ||= {}
-        @converted[checkpoint || :converted] ||= participant.converted?(experiment, checkpoint)
+        converted_key = checkpoint || :converted
+        @converted[converted_key] = participant.converted?(experiment, checkpoint) unless @converted.key?(converted_key)
+        @converted[converted_key]
       end
 
       def converted!(variant, checkpoint, reset: false)