trailguide 0.1.19 → 0.1.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0128e341d1693238ba28d518b32157d62c6d2ae1ea727443c038b5b5f57a116e
-  data.tar.gz: 2d67fe0ee2d33296c95c9040211c3c40a147c9ee99a6b2343977ab42209842d7
+  metadata.gz: c45506f04eec39f23d00fce31f84d1d1e24f4289e2870af413f8928d54cceef8
+  data.tar.gz: 1b6cb001e0fa544f6390e4a82e265922f9ab75b602f4406a2cddf337704fd076
 SHA512:
-  metadata.gz: f1181502a72dab5945d8ccc9c077367062bd4853fc77566036e52643f9df8c5f8b8870a65d201ec542dbf60c210876317c5ab5f9ff3c4d4b1b050b7eaf76bd0d
-  data.tar.gz: dc1791251621abf2c869300f81355aec51285224ebd2272e556388f19e713d7ffcc02df047d7f67ac2204bc77b050ff17d5b4bd006c42b079781c1fa55c3825a
+  metadata.gz: 757e5c2ad76a1143db739638fc60ccaf263d047c2ea3f41172c74368c8c3a2744ba760b0255c6393623ba2266df5e6ec4bff3f3c4e6898370eeefb536b7b5e0b
+  data.tar.gz: 820c4664c60c161dfad8e81dcab8cb61e4137d9961c97e5b0da3f9dfdb5e496692d3bc1bd7f9784645095dfb4be38c75bb73604b80e6e855d42ec2bdac187de0

data/config/initializers/trailguide.rb

@@ -9,6 +9,7 @@ TrailGuide.configure do |config|
 
   # request param for overriding/previewing variants - allows previewing
   # variants with request params
+  # i.e. example.com/somepage/?experiment[my_experiment]=option_b
   config.override_parameter = :experiment
 
   # whether or not participants are allowed to enter variant groups in multiple
@@ -27,7 +28,7 @@ TrailGuide.configure do |config|
   #           in the control group for all except potentially one)
   config.allow_multiple_experiments = false
 
-  # the participant adapter for users
+  # the participant adapter for storing experiment sessions
   #
   # :redis      uses redis to persist user participation
   # :cookie     uses a cookie to persist user participation
@@ -194,6 +195,25 @@ TrailGuide::Experiment.configure do |config|
   # config.on_convert = -> (experiment, variant, checkpoint, metadata) { ... }
 
 
+  # callback that can short-circuit participation based on your own logic, which
+  # gets called *after* all the core engine checks (i.e. that the user is
+  # not excluded or already participating, etc.)
+  #
+  # should return true or false
+  #
+  # config.allow_participation = -> (experiment, metadata) { ... return true }
+
+
+  # callback that can short-circuit conversion based on your own logic, which
+  # gets called *after* all the core engine checks (i.e. that the user is
+  # participating in the experiment, is within the bounds of the experiment
+  # configuration for allow_multiple_*, etc.)
+  #
+  # should return true or false
+  #
+  # config.allow_conversion = -> (experiment, checkpoint, metadata) { ... return true }
+
+
   # callback that can be used to modify the rollout of a selected winner - for
   # example you could use a custom algorithm or even something like the flipper
   # gem to do a "feature rollout" from your control variant to your winner for
@@ -203,3 +223,10 @@ TrailGuide::Experiment.configure do |config|
   #
   # config.rollout_winner = -> (experiment, winner) { ... return variant }
 end
+
+# admin ui configuration
+#
+TrailGuide::Admin.configure do |config|
+  config.title = 'TrailGuide'
+  config.subtitle = 'Experiments and A/B Tests'
+end

data/config/routes.rb

@@ -12,22 +12,20 @@ TrailGuide::Engine.routes.draw do
         via: [:put]
 end
 
-if defined?(TrailGuide::Admin::Engine)
-  TrailGuide::Admin::Engine.routes.draw do
-    resources :experiments, path: '/', only: [:index] do
-      member do
-        match :start,   via: [:put, :post, :get]
-        match :stop,    via: [:put, :post, :get]
-        match :reset,   via: [:put, :post, :get]
-        match :resume,  via: [:put, :post, :get]
-        match :restart, via: [:put, :post, :get]
+TrailGuide::Admin::Engine.routes.draw do
+  resources :experiments, path: '/', only: [:index] do
+    member do
+      match :start,   via: [:put, :post, :get]
+      match :stop,    via: [:put, :post, :get]
+      match :reset,   via: [:put, :post, :get]
+      match :resume,  via: [:put, :post, :get]
+      match :restart, via: [:put, :post, :get]
 
-        match :join,    via: [:put, :post, :get], path: 'join/:variant'
-        match :leave,   via: [:put, :post, :get]
+      match :join,    via: [:put, :post, :get], path: 'join/:variant'
+      match :leave,   via: [:put, :post, :get]
 
-        match :winner,  via: [:put, :post, :get], path: 'winner/:variant'
-        match :clear,   via: [:put, :post, :get]
-      end
+      match :winner,  via: [:put, :post, :get], path: 'winner/:variant'
+      match :clear,   via: [:put, :post, :get]
     end
   end
 end

data/lib/trail_guide/admin.rb

@@ -3,10 +3,5 @@ require "trail_guide/admin/engine"
 module TrailGuide
   module Admin
     include Canfig::Module
-
-    configure do |config|
-      config.title = 'TrailGuide'
-      config.subtitle = 'Experiments and A/B Tests'
-    end
   end
 end

data/lib/trail_guide/catalog.rb

@@ -157,10 +157,9 @@ module TrailGuide
     end
 
     class DSL
-      def self.experiment(name, &block)
+      def self.experiment(name, **opts, &block)
         Class.new(TrailGuide::Experiment) do
-          configure name: name
-          configure &block
+          configure opts.merge({name: name}), &block
         end
       end
     end

data/lib/trail_guide/experiments/base.rb

@@ -1,4 +1,5 @@
 require "trail_guide/experiments/config"
+require "trail_guide/experiments/participant"
 
 module TrailGuide
   module Experiments
@@ -76,11 +77,11 @@ module TrailGuide
         end
 
         def started?
-          !!started_at
+          started_at && started_at <= Time.now
         end
 
         def stopped?
-          !!stopped_at
+          stopped_at && stopped_at <= Time.now
         end
 
         def running?
@@ -162,7 +163,7 @@ module TrailGuide
         :allow_multiple_goals?, :track_winner_conversions?, :callbacks, to: :class
 
       def initialize(participant)
-        @participant = participant
+        @participant = TrailGuide::Experiments::Participant.new(self, participant)
       end
 
       def algorithm
@@ -177,37 +178,49 @@ module TrailGuide
         return control if TrailGuide.configuration.disabled
 
         variant = choose_variant!(override: override, metadata: metadata, **opts)
-        participant.participating!(variant) unless override.present? && !configuration.store_override
         run_callbacks(:on_use, variant, metadata)
         variant
       rescue Errno::ECONNREFUSED, Redis::BaseError, SocketError => e
         run_callbacks(:on_redis_failover, e)
-        return variants.find { |var| var == override } if override.present?
+        return variants.find { |var| var == override } || control if override.present?
         return control
       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 configuration.track_override && running?
-        else
-          if winner?
-            variant = winner
-            return variant unless track_winner_conversions? && running?
-          else
-            return control if excluded
-            return control if !started? && configuration.start_manually
-            start! unless started?
-            return control unless running?
-            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)
+          variant = variants.find { |var| var == override } || control
+          if running?
+            variant.increment_participation! if configuration.track_override
+            participant.participating!(variant) if configuration.store_override
           end
+          return variant
+        end
+
+        if winner?
+          variant = winner
+          variant.increment_participation! if track_winner_conversions?
+          return variant
         end
 
+        return control if excluded
+        return control if !started? && configuration.start_manually
+        start! unless started?
+        return control unless running?
+
+        if participant.participating?
+          variant = participant.variant
+          participant.participating!(variant)
+          return variant
+        end
+
+        return control unless TrailGuide.configuration.allow_multiple_experiments == true || !participant.participating_in_active_experiments?(TrailGuide.configuration.allow_multiple_experiments == false)
+        return control unless allow_participation?(metadata)
+
+        variant = algorithm_choose!(metadata: metadata)
         variant.increment_participation!
+        participant.participating!(variant)
         run_callbacks(:on_choose, variant, metadata)
         variant
       end
@@ -218,17 +231,18 @@ module TrailGuide
 
       def convert!(checkpoint=nil, metadata: nil)
         return false if !running? || (winner? && !track_winner_conversions?)
-        return false unless participating?
+        return false unless participant.participating?
         raise InvalidGoalError, "Invalid goal checkpoint `#{checkpoint}` for `#{experiment_name}`." unless checkpoint.present? || goals.empty?
         raise InvalidGoalError, "Invalid goal checkpoint `#{checkpoint}` for `#{experiment_name}`." unless checkpoint.nil? || goals.any? { |goal| goal == checkpoint.to_s.underscore.to_sym }
         # TODO eventually allow progressing through funnel checkpoints towards goals
-        if converted?(checkpoint)
+        if participant.converted?(checkpoint)
           return false unless allow_multiple_conversions?
-        elsif converted?
+        elsif participant.converted?
           return false unless allow_multiple_goals?
         end
+        return false unless allow_conversion?(checkpoint, metadata)
 
-        variant = variants.find { |var| var == participant[storage_key] }
+        variant = participant.variant
         # TODO eventually only reset if we're at the final goal in a funnel
         participant.converted!(variant, checkpoint, reset: !reset_manually?)
         variant.increment_conversion!(checkpoint)
@@ -239,22 +253,24 @@ module TrailGuide
         return false
       end
 
-      def participating?
-        participant.participating?(self)
+      def allow_participation?(metadata=nil)
+        return true if callbacks[:allow_participation].empty?
+        run_callbacks(:allow_participation, metadata)
       end
 
-      def converted?(checkpoint=nil)
-        participant.converted?(self, checkpoint)
+      def allow_conversion?(checkpoint=nil, metadata=nil)
+        return true if callbacks[:allow_conversion].empty?
+        run_callbacks(:allow_conversion, checkpoint, metadata)
       end
 
       def run_callbacks(hook, *args)
         return unless callbacks[hook]
-        if hook == :rollout_winner
-          callbacks[hook].reduce(args[0]) do |winner, callback|
+        if [:allow_participation, :allow_conversion, :rollout_winner].include?(hook)
+          callbacks[hook].reduce(args.slice!(0,1)[0]) do |result, callback|
             if callback.respond_to?(:call)
-              callback.call(self, winner)
+              callback.call(self, result, *args)
             else
-              send(callback, self, winner)
+              send(callback, self, result, *args)
             end
           end
         else

data/lib/trail_guide/experiments/config.rb

@@ -12,7 +12,7 @@ module TrailGuide
         :on_start, :on_stop, :on_resume, :on_winner, :on_reset, :on_delete,
         :on_choose, :on_use, :on_convert,
         :on_redis_failover,
-        :rollout_winner
+        :allow_participation, :allow_conversion, :rollout_winner
       ].freeze
 
       def default_config
@@ -185,6 +185,16 @@ module TrailGuide
         self[:on_redis_failover] << (meth || block)
       end
 
+      def allow_participation(meth=nil, &block)
+        self[:allow_participation] ||= []
+        self[:allow_participation] << (meth || block)
+      end
+
+      def allow_conversion(meth=nil, &block)
+        self[:allow_conversion] ||= []
+        self[:allow_conversion] << (meth || block)
+      end
+
       def rollout_winner(meth=nil, &block)
         self[:rollout_winner] ||= []
         self[:rollout_winner] << (meth || block)

data/lib/trail_guide/experiments/participant.rb

@@ -0,0 +1,33 @@
+module TrailGuide
+  module Experiments
+    class Participant
+      attr_reader :experiment, :participant
+
+      def initialize(experiment, participant)
+        @experiment = experiment
+        @participant = participant
+      end
+
+      def participating?
+        participant.participating?(experiment)
+      end
+
+      def converted?(checkpoint=nil)
+        participant.converted?(experiment, checkpoint)
+      end
+
+      def variant
+        participant.variant(experiment)
+      end
+
+      def method_missing(meth, *args, &block)
+        return participant.send(meth, *args, &block) if participant.respond_to?(meth, true)
+        super
+      end
+
+      def respond_to_missing?(meth, include_private=false)
+        participant.respond_to?(meth, include_private)
+      end
+    end
+  end
+end

data/lib/trail_guide/participant.rb

@@ -6,6 +6,7 @@ module TrailGuide
     def initialize(context, adapter: nil)
       @context = context
       @adapter = adapter.new(context) unless adapter.nil?
+      cleanup_inactive_experiments!
     end
 
     def adapter
@@ -128,5 +129,19 @@ module TrailGuide
         experiment && !experiment.combined? && experiment.running? && participating?(experiment, include_control)
       end
     end
+
+    def cleanup_inactive_experiments!
+      return false if adapter.keys.empty?
+
+      adapter.keys.each do |key|
+        experiment_name = key.to_s.split(":").first.to_sym
+        experiment = TrailGuide.catalog.find(experiment_name)
+        if !experiment || !experiment.started?
+          adapter.delete(key)
+        end
+      end
+
+      return true
+    end
   end
 end

data/lib/trail_guide/spec_helper.rb

@@ -1,15 +1,31 @@
 module TrailGuide
   module SpecHelper
 
-    def use_trailguide(**experiments)
-      experiments.each do |exp,var|
-        experiment = TrailGuide.catalog.find(exp)
-        raise ArgumentError, "Experiment not found `#{exp}`" unless experiment.present?
-        variant = experiment.variants.find { |v| v == var }
-        raise ArgumentError, "Variant `#{var}` not found in experiment `#{exp}`" unless variant.present?
-
-        allow_any_instance_of(experiment).to receive(:choose!).and_return(variant)
+    def use_trailguide(**experiments, &block)
+      if block_given?
+        before do
+          use_trailguide(**experiments)
+        end
+
+        yield
+      else
+        experiments.each do |exp,var|
+          experiment = TrailGuide.catalog.find(exp)
+          raise ArgumentError, "Experiment not found `#{exp}`" unless experiment.present?
+          variant = experiment.variants.find { |v| v == var }
+          raise ArgumentError, "Variant `#{var}` not found in experiment `#{exp}`" unless variant.present?
+
+          allow_any_instance_of(experiment).to receive(:choose!).and_return(variant)
+        end
       end
     end
+    alias_method :with_trailguide, :use_trailguide
+  end
+end
+
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.extend  TrailGuide::SpecHelper
+    config.include TrailGuide::SpecHelper
   end
 end

data/lib/trail_guide/variant.rb

@@ -53,7 +53,8 @@ module TrailGuide
     end
 
     def reset!
-      delete! && save!
+      delete!
+      save!
     end
 
     def participants

data/lib/trail_guide/version.rb

@@ -2,7 +2,7 @@ module TrailGuide
   module Version
     MAJOR = 0
     MINOR = 1
-    PATCH = 19
+    PATCH = 20
     VERSION = "#{MAJOR}.#{MINOR}.#{PATCH}"
 
     class << self

data/lib/trailguide.rb

@@ -1,5 +1,6 @@
 require "canfig"
 require "redis"
+require "trail_guide/version"
 require "trail_guide/config"
 require "trail_guide/errors"
 require "trail_guide/adapters"
@@ -11,7 +12,7 @@ require "trail_guide/combined_experiment"
 require "trail_guide/catalog"
 require "trail_guide/helper"
 require "trail_guide/engine"
-require "trail_guide/version"
+require "trail_guide/admin"
 
 module TrailGuide
   include Canfig::Module

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailguide
 version: !ruby/object:Gem::Version
-  version: 0.1.19
+  version: 0.1.20
 platform: ruby
 authors:
 - Mark Rebec
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-11 00:00:00.000000000 Z
+date: 2019-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -159,6 +159,7 @@ files:
 - lib/trail_guide/experiments/base.rb
 - lib/trail_guide/experiments/combined_config.rb
 - lib/trail_guide/experiments/config.rb
+- lib/trail_guide/experiments/participant.rb
 - lib/trail_guide/helper.rb
 - lib/trail_guide/participant.rb
 - lib/trail_guide/spec_helper.rb