trailguide 0.1.17 → 0.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4bc166a7ac69aa3e1c4eb9d72e43004431b7263ee49f29959bcbb50bce260fa
-  data.tar.gz: 4371c7fd6844f62602bc71884855ada79c9d2cf1ff78a511ef139432ec98cced
+  metadata.gz: 4bfe3a4830dd35f2af7fe1849c9d92254a0f422db41a153e3360077fb7f6cde7
+  data.tar.gz: bbeed95f2e497288e37e99b000b193a907e176a73ce596cdd81110f381abba27
 SHA512:
-  metadata.gz: 3d57bc137ce240bf6090a72a3f3fb7031b2488919c0bfb44b20d9389a918ca4be02b79c5dc3d20e7af68bfcba69b81eaddbce4b954fbd22cde21b51038f85398
-  data.tar.gz: b7691b7ae52dd19c7d2a71d7417a2626a8dcfed7c3c8d544a5431580e24d5aac09378ee1d883471e206860bf219f234bb795e105c9141b38edfa6611259f1e14
+  metadata.gz: b6fe56eb7a87037e2c081d455ac304325071294a6180aedb0c4cda9dafd0382c4e9290e906b331f50c7e04bff01dfea342d5a265bddc38fd729d3635d6432d5e
+  data.tar.gz: 5ecc3ccb399e13216f3dd8e88c2ba9884cca993c930cfeb300ac27643e077abd0c151691e29533a6d9998d2323811a3875366f0032901755d4506ccdaae3a478

data/README.md

@@ -1,28 +1,181 @@
 # TrailGuide
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+TrailGuide is a rails engine providing a framework for running user experiments and A/B tests in rails apps.
 
-## Installation
-Add this line to your application's Gemfile:
+## Acknowledgements
 
-```ruby
+This gem is heavily inspired by the [split gem](https://github.com/splitrb/split). I've used split many times in the past and am a fan. It's an excellent alternative to trailguide, and really your best bet if you're not using rails. If you've used split in the past, you'll probably see a lot of familiar concepts and similarly named configuration variables. Parts of this project are even loosely modeled after some of the more brilliant patterns in split - like the user adapters for persistence.
+
+### Motivation
+
+While working on a project to more deeply integrate custom experiments into a rails app, I found myself digging into the split internals. Split has been the go-to for A/B testing in ruby for a while. It's grown and evolved over the years, but as I explored the codebase and the github repo it became clear I wouldn't be able to do a lot of what was required for the project without overriding much of the existing behavior. Additionally, there are some differing opinions and approaches taken here that directly conflicted with split's defaults - for example the way "combined experiments" work, or how split allows defining and running experiments directly inline, while trailguide requires configuration.
+
+After spending so much time with split and struggling with some of the implementation, I saw what I thought was a clear model and path forward for a more customizable and extensible rails-focused framework.
+
+## Getting Started
+
+### Requirements
+
+Currently only rails 5.x is officially supported, and trailguide requires redis as a datastore for experiment metadata.
+
+`docker-compose` is a great way to run redis in development. Take a look at the `docker-compose.yml` in the root of this repo for an example.
+
+### Installation
+
+Add this line to your Gemfile:
+
+```
 gem 'trailguide'
 ```
 
-And then execute:
-```bash
-$ bundle
+Then run `bundle install`.
+
+## Configuration
+
+The core engine and base experiment class have a number of configuration flags available to customize behavior and hook into various pieces of functionality. The preferred way to configure trailguide is via a config initializer, and the gem sets it's config defaults via it's own initializer.
+
+```ruby
+# config/initializers/trailguide.rb
+
+TrailGuide.configure do |config|
+  config.redis = Redis.new(url: ENV['REDIS_URL'])
+  # ...
+end
+
+TrailGuide::Experiment.configure do |config|
+  config.algorithm = :weighted
+  # ...
+end
+```
+
+Take a look at `config/initializers/trailguide.rb` in this for a full list of defaults and examples of available configuration.
+
+### Defining Experiments
+
+Before you can start running experiments in your app, you'll need to define and configure them. There are a few options for defining experiments - YAML files, a ruby DSL, or custom classes - and they all inherit the base `TrailGuide::Experiment.configuration` for defaults, which can be overridden per-experiment.
+
+#### YAML
+
+YAML files are an easy way to configure simple experiments. They can be put in `config/experiments.yml` or `config/experiments/**/*.yml`:
+
+```yaml
+# config/experiments.yml
+
+simple_ab:
+  variants:
+    - 'option_a'
+    - 'option_b'
+```
+
+```yaml
+# config/experiments/search/widget.yml
+
+search_widget:
+  start_manually: true
+  algorithm: 'distributed'
+  variants:
+    - 'basic'
+    - 'simple'
+    - 'advanced'
+```
+
+#### Ruby DSL
+
+The ruby DSL provides a more dynamic and flexible way to configure your experiments, and allows you to define custom behavior via callbacks and options. You can put these experiments in `config/experiments.rb` or `config/experiments/**/*.rb`:
+
+```ruby
+# config/experiments.rb
+
+experiment :search_widget do |config|
+  config.start_manually = true
+  config.algorithm = :distributed
+  config.allow_multiple_goals = true
+
+  variant :basic
+  variant :simple, control: true
+  variant :advanced
+
+  goal :interacted
+  goal :searched
+
+  on_choose do |experiment, variant, metadata|
+    # ... send a track to some third party service ...
+  end
+
+  on_convert do |experiment, variant, goal, metadata|
+    # ... send a track to some third party service ...
+  end
+end
 ```
 
-Or install it yourself as:
-```bash
-$ gem install trailguide
+#### Custom Classes
+
+You can also take it a step further and define your own custom experiment classes, inheriting from `TrailGuide::Experiment`. This allows you to add or override all sorts of additional behavior on top of all the standard configuration provided by the DSL. In fact, the YAML and ruby DSL configs both use this to parse experiments into anonmymous classes extending `TrailGuide::Experiment`.
+
+You can put these classes anywhere rails will autoload them (or require them yourself), but I recommend `app/experiments/**/*.rb`:
+
+```ruby
+# app/experiments/my_complex_experiment.rb
+
+class MyComplexExperiment < TrailGuide::Experiment
+
+  # all standard experiment config goes in the `configure` block
+  configure do |config|
+    config.reset_manually = true
+
+    control :option_a
+    variant :option_b
+    variant :option_c
+    variant :option_d
+
+    on_start do |experiment|
+      # ... do some custom stuff when the experiment is started ...
+    end
+  end
+
+  # override the experiment `choose!` method, and maybe do some custom stuff
+  # depending on custom options you pass in
+  def choose!(**opts)
+    if opts[:foo] == :bar
+      return control
+    else
+      super(**opts)
+    end
+  end
+
+  def foobar
+    # ... you can define whatever other custom methods, mixins and behaviors ...
+  end
+
+end
 ```
 
+You can also use inheritance to setup base experiments and inherit configuration:
+
+```ruby
+
+class ApplicationExperiment < TrailGuide::Experiment
+  configure do |config|
+    # ... config, variants, etc.
+  end
+  # ... custom behavior, etc.
+end
+
+class MyAppExperiment < ApplicationExperiment
+  # inherits config from ApplicationExperiment
+end
+
+class MyDefaultExperiment < TrailGuide::Experiment
+  # inherits from configured trailguide defaults
+end
+```
+
+## Usage
+
 ## Contributing
+
 Contribution directions go here.
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/views/layouts/trail_guide/admin/_footer.erb

@@ -1,5 +1,10 @@
-<div class="footer bg-light">
-  <div class="text-right">
-    <%= link_to "TrailGuide v#{TrailGuide::Version::VERSION}", "https://github.com/markrebec/trailguide", target: :blank, class: "text-muted" %>
+<div class="footer container-fluid bg-light">
+  <div class="row">
+    <div class="col-sm text-left">
+      <%= link_to "TrailGuide v#{TrailGuide::Version::VERSION}", "https://github.com/markrebec/trailguide", target: :blank, class: "text-muted" %>
+    </div>
+    <div class="col-sm text-right">
+      <small class="text-muted"><%= TrailGuide.redis._client.id %><%= "/#{TrailGuide.redis.namespace}" if TrailGuide.redis.respond_to?(:namespace) %></small>
+    </div>
   </div>
 </div>

data/app/views/layouts/trail_guide/admin/_header.erb

@@ -3,6 +3,12 @@
     <%= image_tag "trail_guide/trailguide.png" %>
     <%= TrailGuide::Admin.configuration.title %>
   <% end %>
+  <div class="col-sm text-center">
+    <strong class="total"><%= TrailGuide.catalog.to_a.count %></strong> experiments
+    <span>/</span>
+    <strong class="running"><%= TrailGuide.catalog.running.count %></strong> running
+    <span>/</span>
+    <strong class="stopped"><%= TrailGuide.catalog.stopped.count %></strong> stopped
+  </div>
   <span class="navbar-brand"><small class="text-muted"><%= TrailGuide::Admin.configuration.subtitle %></small></span>
 </nav>
-

data/config/initializers/trailguide.rb

@@ -0,0 +1,205 @@
+# top-level trailguide rails engine configuration
+#
+TrailGuide.configure do |config|
+  # url string or initialized Redis object
+  config.redis = ENV['REDIS_URL']
+
+  # globally disable trailguide - returns control everywhere
+  config.disabled = false
+
+  # request param for overriding/previewing variants - allows previewing
+  # variants with request params
+  config.override_parameter = :experiment
+
+  # whether or not participants are allowed to enter variant groups in multiple
+  # experiments
+  #
+  # true      participants are entered into any experiments they encounter
+  #
+  # false     as soon as a participant enters an experiment, they are prevented
+  #           from entering any future experiments (they will only ever be in a
+  #           single experiment)
+  #
+  # :control  participants can enter any number of experiments as long as they
+  #           are in the control groups, but as soon as they enter a non-control
+  #           variant in any experiment, they will be prevented from entering
+  #           any future experiments (they may be in multiple experiments, but
+  #           in the control group for all except potentially one)
+  config.allow_multiple_experiments = false
+
+  # the participant adapter for users
+  #
+  # :redis      uses redis to persist user participation
+  # :cookie     uses a cookie to persist user participation
+  # :session    uses the rails session to persist user participation
+  # :anonymous  does not persist, can only convert in the same script/request
+  #             execution while holding onto a reference to the object
+  # :multi      allows using multiple adapters based on logic you define - i.e.
+  #             use :redis if :current_user is present or use :cookie if not
+  # :unity      a custom adapter for unity that helps track experiments across
+  #             logged in/out sessions and across devices
+  config.adapter = :cookie
+
+  # callback when your participant adapter fails to initialize, and trailguide
+  # falls back to the anonymous adapter
+  config.on_adapter_failover = -> (adapter, error) do
+    Rails.logger.error("#{error.class.name}: #{error.message}")
+  end
+
+  # list of user agents used by the default request filter proc below when
+  # provided, can be an array or a proc that returns an array
+  #
+  # if using a proc, make sure it returns an array:
+  # -> { return [...] }
+  #
+  # config.filtered_user_agents = []
+
+  # list of ip addresses used by the default request filter proc below when
+  # provided, can be an array or a proc that returns an array
+  #
+  # if using a proc, make sure it returns an array:
+  # -> { return [...] }
+  #
+  # config.filtered_ip_addresses = []
+
+  # default request filter logic uses the configured filtered ip and user
+  # agents above, all requests matching this filter will be excluded from being
+  # entered into experiments - used to block bots, crawlers, scrapers, etc.
+  config.request_filter = -> (context) do
+    is_preview? ||
+      is_filtered_user_agent? ||
+      is_filtered_ip_address?
+  end
+end
+
+# base experiment configuration
+#
+TrailGuide::Experiment.configure do |config|
+  # the default algorithm to use for new experiments
+  config.algorithm = :weighted
+
+  # whether or not experiments must be started manually
+  #
+  # true    experiments must be started manually via the admin UI or console
+  # false   experiments will start the first time they're encountered by a user
+  config.start_manually = true
+
+  # whether or not participants will be reset upon conversion
+  #
+  # true    participants will only be entered into the experiment once, and the
+  #         variant group they belong to is sticky for the duration
+  # false   participants will be reset upon conversion and be able to re-enter
+  #         the experiment if they encounter it again
+  config.reset_manually = true
+
+  # whether or not to enter participants into a variant when using the override
+  # parameter to preview variants
+  #
+  # true    using overrides to preview experiments will enter participants into
+  #         that variant group
+  # false   using overrides to preview experiments will not enter participants
+  #         into the experment (won't persist their variant group)
+  config.store_override = false
+
+  # whether or not we track participants when using the override parameter to
+  # preview variants
+  #
+  # true    using overrides to preview experiments will increment the
+  #         participant count for the override variant
+  # false   using overrides to preview experiments will not increment the
+  #         participant count for the override variant
+  config.track_override = false
+  
+  # whether or not to continue tracking conversions after a winner has been
+  # selected in order to continue monitoring performance of the variant
+  #
+  # true    continues to track conversions after a winner has been selected (as
+  #         long as the experiment is still running)
+  # false   all conversion and participation tracking stops once a winner has
+  #         been selected
+  config.track_winner_conversions = false
+
+  # whether or not to allow multiple conversions of the same goal, or default
+  # conversion if no goals are defined
+  #
+  # true    tracks multiple participant conversions for the same goal as long
+  #         as they haven't been reset (see config.reset_manually)
+  # false   prevents tracking multiple conversions for a single participant
+  config.allow_multiple_conversions = false
+
+  # whether or not to allow participants to convert for multiple defined goals
+  #
+  # true    allows participants to convert more than one goal as long as they
+  #         haven't been reset (see config.reset_manually)
+  # false   prevents converting to multiple goals for a single participant
+  config.allow_multiple_goals = false
+
+  # whether or not to skip the request filtering for this experiment - can be
+  # useful when defining content-based experiments with custom algorithms which
+  # bucket participants strictly based on additional content metadata and you
+  # want to expose those variants to crawlers and bots
+  #
+  # true    requests that would otherwise be filtered based on your
+  #         TrailGuide.configuration.request_filter config will instead be
+  #         allowed through to this experiment
+  # false   default behavior, requests will be filtered based on your config
+  config.skip_request_filter = false
+
+  # callback when connecting to redis fails and trailguide falls back to always
+  # returning control variants
+  config.on_redis_failover = -> (experiment, error) do
+    Rails.logger.error("#{error.class.name}: #{error.message}")
+  end
+
+  # callback on experiment start, either manually via UI/console or
+  # automatically depending on config.start_manually, can be used for logging,
+  # tracking, etc.
+  #
+  # config.on_start = -> (experiment) { ... }
+
+  # callback on experiment stop manually via UI/console, can be used for
+  # logging, tracking, etc.
+  #
+  # config.on_stop = -> (experiment) { ... }
+
+  # callback on experiment resume manually via UI/console, can be used for
+  # logging, tracking, etc.
+  #
+  # config.on_resume = -> (experiment) { ... }
+
+  # callback on experiment reset manually via UI/console, can be used for
+  # logging, tracking, etc.
+  #
+  # config.on_reset = -> (experiment) { ... }
+
+  # callback when a winner is selected manually via UI/console, can be used for
+  # logging, tracking, etc.
+  #
+  # config.on_winner = -> (experiment, winner) { ... }
+
+
+  # callback when a participant is entered into a variant for the first time,
+  # can be used for logging, tracking, etc.
+  #
+  # config.on_choose = -> (experiment, variant, metadata) { ... }
+
+  # callback every time a participant is returned a variant in the experiment,
+  # can be used for logging, tracking, etc.
+  #
+  # config.on_use = -> (experiment, variant, metadata) { ... }
+
+  # callback when a participant converts for a variant in the experiment, can be
+  # used for logging, tracking, etc.
+  #
+  # config.on_convert = -> (experiment, variant, checkpoint, metadata) { ... }
+
+
+  # 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
+  # all users
+  #
+  # must return an experiment variant
+  #
+  # config.rollout_winner = -> (experiment, winner) { ... return variant }
+end

data/lib/trail_guide/catalog.rb

@@ -1,14 +1,5 @@
 module TrailGuide
   class Catalog
-    class DSL
-      def self.experiment(name, &block)
-        Class.new(TrailGuide::Experiment) do
-          configure name: name
-          configure &block
-        end
-      end
-    end
-
     include Enumerable
 
     class << self
@@ -70,7 +61,7 @@ module TrailGuide
           name: name.to_s.underscore.to_sym,
           parent: combined,
           combined: [],
-          variants: combined.configuration.variants.map { |var| Variant.new(experiment, var.name, metadata: var.metadata, weight: var.weight, control: var.control?) },
+          variants: combined.configuration.variants.map { |var| var.dup(experiment) }
           # TODO also map goals once they're separate classes
         })
         experiment
@@ -98,6 +89,18 @@ module TrailGuide
       end.flatten
     end
 
+    def started
+      to_a.select(&:started?)
+    end
+
+    def running
+      to_a.select(&:running?)
+    end
+
+    def stopped
+      to_a.select(&:stopped?)
+    end
+
     def find(name)
       if name.is_a?(Class)
         experiments.find { |exp| exp == name }
@@ -152,5 +155,18 @@ module TrailGuide
     def respond_to_missing?(meth, include_private=false)
       experiments.respond_to?(meth, include_private)
     end
+
+    class DSL
+      def self.experiment(name, &block)
+        Class.new(TrailGuide::Experiment) do
+          configure name: name
+          configure &block
+        end
+      end
+    end
+  end
+
+  def self.catalog
+    TrailGuide::Catalog.catalog
   end
 end

data/lib/trail_guide/config.rb

@@ -0,0 +1,46 @@
+module TrailGuide
+  class Config < Canfig::Config
+    DEFAULT_KEYS = [
+      :redis, :disabled, :override_parameter, :allow_multiple_experiments,
+      :adapter, :on_adapter_failover, :filtered_ip_addresses,
+      :filtered_user_agents, :request_filter
+    ].freeze
+
+    def initialize(*args, **opts, &block)
+      args = args.concat(DEFAULT_KEYS)
+      super(*args, **opts, &block)
+    end
+
+    def configure(*args, &block)
+      super(*args) do |config|
+        yield(config, TrailGuide::Experiment.configuration) if block_given?
+      end
+    end
+
+    def redis
+      @redis ||= begin
+        if ['Redis', 'Redis::Namespace'].include?(self[:redis].class.name)
+          self[:redis]
+        else
+          Redis.new(url: self[:redis])
+        end
+      end
+    end
+
+    def filtered_user_agents
+      @filtered_user_agents ||= begin
+        uas = self[:filtered_user_agents]
+        uas = uas.call if uas.respond_to?(:call)
+        uas || []
+      end
+    end
+
+    def filtered_ip_addresses
+      @filtered_ip_addresses ||= begin
+        ips = self[:filtered_ip_addresses]
+        ips = ips.call if ips.respond_to?(:call)
+        ips || []
+      end
+    end
+  end
+end

data/lib/trail_guide/experiment.rb

@@ -2,7 +2,9 @@ require "trail_guide/experiments/base"
 
 module TrailGuide
   class Experiment < Experiments::Base
+
     def self.inherited(child)
+      child.instance_variable_set :@configuration, Experiments::Config.new(child, inherit: self.configuration)
       TrailGuide.catalog.register(child)
     end
   end

data/lib/trail_guide/experiments/base.rb

@@ -6,7 +6,8 @@ module TrailGuide
       class << self
         delegate :metric, :algorithm, :control, :goals, :callbacks, :combined,
           :combined?, :allow_multiple_conversions?, :allow_multiple_goals?,
-          :track_winner_conversions?, to: :configuration
+          :track_winner_conversions?, :start_manually?, :reset_manually?,
+          to: :configuration
         alias_method :funnels, :goals
 
         def configuration
@@ -17,10 +18,6 @@ module TrailGuide
           configuration.configure(*args, &block)
         end
 
-        def resettable?
-          !configuration.reset_manually
-        end
-
         def experiment_name
           configuration.name
         end
@@ -35,7 +32,7 @@ module TrailGuide
 
         def run_callbacks(hook, *args)
           return unless callbacks[hook]
-          return args[0] if hook == :return_winner
+          return args[0] if hook == :rollout_winner
           args.unshift(self)
           callbacks[hook].each do |callback|
             if callback.respond_to?(:call)
@@ -140,7 +137,8 @@ module TrailGuide
               algorithm: algorithm.name,
               variants: variants.as_json,
               goals: goals.as_json,
-              resettable: resettable?,
+              start_manually: start_manually?,
+              reset_manually: reset_manually?,
               allow_multiple_conversions: allow_multiple_conversions?,
               allow_multiple_goals: allow_multiple_goals?
             },
@@ -159,9 +157,9 @@ module TrailGuide
 
       attr_reader :participant
       delegate :configuration, :experiment_name, :variants, :control, :goals,
-        :storage_key, :running?, :started?, :started_at, :start!, :resettable?,
-        :winner?, :allow_multiple_conversions?, :allow_multiple_goals?,
-        :track_winner_conversions?, :callbacks, to: :class
+        :storage_key, :running?, :started?, :started_at, :start!,
+        :start_manually?, :reset_manually?, :winner?, :allow_multiple_conversions?,
+        :allow_multiple_goals?, :track_winner_conversions?, :callbacks, to: :class
 
       def initialize(participant)
         @participant = participant
@@ -172,7 +170,7 @@ module TrailGuide
       end
 
       def winner
-        run_callbacks(:return_winner, self.class.winner)
+        run_callbacks(:rollout_winner, self.class.winner)
       end
 
       def choose!(override: nil, metadata: nil, **opts)
@@ -203,7 +201,7 @@ module TrailGuide
             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) 
+            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
@@ -232,7 +230,7 @@ module TrailGuide
 
         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?)
+        participant.converted!(variant, checkpoint, reset: !reset_manually?)
         variant.increment_conversion!(checkpoint)
         run_callbacks(:on_convert, variant, checkpoint, metadata)
         variant
@@ -251,7 +249,7 @@ module TrailGuide
 
       def run_callbacks(hook, *args)
         return unless callbacks[hook]
-        if hook == :return_winner
+        if hook == :rollout_winner
           callbacks[hook].reduce(args[0]) do |winner, callback|
             if callback.respond_to?(:call)
               callback.call(self, winner)

data/lib/trail_guide/experiments/config.rb

@@ -1,71 +1,76 @@
 module TrailGuide
   module Experiments
     class Config < Canfig::Config
-      ENGINE_CONFIG_KEYS = [
+      DEFAULT_KEYS = [
+        :name, :summary, :preview_url, :algorithm, :metric, :variants, :goals,
         :start_manually, :reset_manually, :store_override, :track_override,
-        :algorithm, :allow_multiple_conversions, :allow_multiple_goals,
-        :track_winner_conversions
+        :combined, :allow_multiple_conversions, :allow_multiple_goals,
+        :track_winner_conversions, :skip_request_filter
       ].freeze
 
-      def self.engine_config
-        ENGINE_CONFIG_KEYS.map do |key|
-          [key, TrailGuide.configuration.send(key.to_sym)]
-        end.to_h
-      end
+      CALLBACK_KEYS = [
+        :on_start, :on_stop, :on_resume, :on_winner, :on_reset, :on_delete,
+        :on_choose, :on_use, :on_convert,
+        :on_redis_failover,
+        :rollout_winner
+      ].freeze
 
-      def self.default_config
-        { name: nil,
-          metric: nil,
+      def default_config
+        DEFAULT_KEYS.map do |key|
+          [key, nil]
+        end.to_h.merge({
           variants: [],
           goals: [],
-          combined: [],
-          summary: nil,
-          preview_url: nil,
-        }
-      end
-
-      def self.callbacks_config
-        {
-          callbacks: {
-            on_choose:          [TrailGuide.configuration.on_experiment_choose].flatten.compact,
-            on_use:             [TrailGuide.configuration.on_experiment_use].flatten.compact,
-            on_convert:         [TrailGuide.configuration.on_experiment_convert].flatten.compact,
-            on_start:           [TrailGuide.configuration.on_experiment_start].flatten.compact,
-            on_stop:            [TrailGuide.configuration.on_experiment_stop].flatten.compact,
-            on_resume:          [TrailGuide.configuration.on_experiment_resume].flatten.compact,
-            on_winner:          [TrailGuide.configuration.on_experiment_winner].flatten.compact,
-            on_reset:           [TrailGuide.configuration.on_experiment_reset].flatten.compact,
-            on_delete:          [TrailGuide.configuration.on_experiment_delete].flatten.compact,
-            on_redis_failover:  [TrailGuide.configuration.on_redis_failover].flatten.compact,
-            return_winner:      [TrailGuide.configuration.return_experiment_winner].flatten.compact,
-          }
-        }
+          combined: []
+        }).merge(callback_config)
+      end
+
+      def callback_config
+        CALLBACK_KEYS.map do |key|
+          [key, []]
+        end.to_h
       end
 
       attr_reader :experiment
 
       def initialize(experiment, *args, **opts, &block)
         @experiment = experiment
-        opts = opts.merge(self.class.engine_config)
-        opts = opts.merge(self.class.default_config)
-        opts = opts.merge(self.class.callbacks_config)
+        opts = opts.merge(default_config)
+        ancestor = opts.delete(:inherit)
+        if ancestor.present?
+          keys = opts.keys.dup.concat(args).concat(DEFAULT_KEYS).concat(CALLBACK_KEYS).uniq
+          opts = opts.merge(ancestor.to_h.slice(*keys))
+          opts[:name] = nil
+          opts[:goals] = ancestor.goals.dup
+          opts[:combined] = ancestor.combined.dup
+          opts[:variants] = ancestor.variants.map { |var| var.dup(experiment) }
+          opts = opts.merge(ancestor.callbacks.map { |k,v| [k,[v].flatten.compact] }.to_h)
+        end
         super(*args, **opts, &block)
       end
 
-      def resettable?
-        !reset_manually
+      def start_manually?
+        !!start_manually
+      end
+
+      def reset_manually?
+        !!reset_manually
       end
 
       def allow_multiple_conversions?
-        allow_multiple_conversions
+        !!allow_multiple_conversions
       end
 
       def allow_multiple_goals?
-        allow_multiple_goals
+        !!allow_multiple_goals
       end
 
       def track_winner_conversions?
-        track_winner_conversions
+        !!track_winner_conversions
+      end
+
+      def skip_request_filter?
+        !!skip_request_filter
       end
 
       def name
@@ -126,48 +131,63 @@ module TrailGuide
         !!preview_url
       end
 
+      def callbacks
+        to_h.slice(*CALLBACK_KEYS).map { |k,v| [k, [v].flatten.compact] }.to_h
+      end
+
       def on_choose(meth=nil, &block)
-        callbacks[:on_choose] << (meth || block)
+        self[:on_choose] ||= []
+        self[:on_choose] << (meth || block)
       end
 
       def on_use(meth=nil, &block)
-        callbacks[:on_use] << (meth || block)
+        self[:on_use] ||= []
+        self[:on_use] << (meth || block)
       end
 
       def on_convert(meth=nil, &block)
-        callbacks[:on_convert] << (meth || block)
+        self[:on_convert] ||= []
+        self[:on_convert] << (meth || block)
       end
 
       def on_start(meth=nil, &block)
-        callbacks[:on_start] << (meth || block)
+        self[:on_start] ||= []
+        self[:on_start] << (meth || block)
       end
 
       def on_stop(meth=nil, &block)
-        callbacks[:on_stop] << (meth || block)
+        self[:on_stop] ||= []
+        self[:on_stop] << (meth || block)
       end
 
       def on_resume(meth=nil, &block)
-        callbacks[:on_resume] << (meth || block)
+        self[:on_resume] ||= []
+        self[:on_resume] << (meth || block)
       end
 
       def on_winner(meth=nil, &block)
-        callbacks[:on_winner] << (meth || block)
+        self[:on_winner] ||= []
+        self[:on_winner] << (meth || block)
       end
 
       def on_reset(meth=nil, &block)
-        callbacks[:on_reset] << (meth || block)
+        self[:on_reset] ||= []
+        self[:on_reset] << (meth || block)
       end
 
       def on_delete(meth=nil, &block)
-        callbacks[:on_delete] << (meth || block)
+        self[:on_delete] ||= []
+        self[:on_delete] << (meth || block)
       end
 
       def on_redis_failover(meth=nil, &block)
-        callbacks[:on_redis_failover] << (meth || block)
+        self[:on_redis_failover] ||= []
+        self[:on_redis_failover] << (meth || block)
       end
 
-      def return_winner(meth=nil, &block)
-        callbacks[:return_winner] << (meth || block)
+      def rollout_winner(meth=nil, &block)
+        self[:rollout_winner] ||= []
+        self[:rollout_winner] << (meth || block)
       end
     end
   end

data/lib/trail_guide/helper.rb

@@ -142,6 +142,7 @@ module TrailGuide
       end
 
       def exclude_visitor?
+        return false if experiment.configuration.skip_request_filter?
         instance_exec(context, &TrailGuide.configuration.request_filter)
       end
 

data/lib/trail_guide/variant.rb

@@ -2,6 +2,10 @@ module TrailGuide
   class Variant
     attr_reader :experiment, :name, :metadata, :weight
 
+    def dup(experiment)
+      self.class.new(experiment, name, metadata: metadata, weight: weight, control: control?)
+    end
+
     def initialize(experiment, name, metadata: {}, weight: 1, control: false)
       @experiment = experiment
       @name = name.to_s.underscore.to_sym

data/lib/trail_guide/version.rb

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

data/lib/trailguide.rb

@@ -1,5 +1,6 @@
 require "canfig"
 require "redis"
+require "trail_guide/config"
 require "trail_guide/errors"
 require "trail_guide/adapters"
 require "trail_guide/algorithms"
@@ -14,74 +15,9 @@ require "trail_guide/version"
 
 module TrailGuide
   include Canfig::Module
+  @@configuration = TrailGuide::Config.new
 
-  configure do |config|
-    config.redis = ENV['REDIS_URL']
-    config.disabled = false
-    config.start_manually = true
-    config.reset_manually = true
-    config.store_override = false
-    config.track_override = false
-    config.override_parameter = :experiment
-    config.algorithm = :weighted
-    config.adapter = :multi
-    config.allow_multiple_experiments = true # false / :control
-    config.track_winner_conversions = false
-    config.allow_multiple_conversions = false
-    config.allow_multiple_goals = false
-
-    config.on_redis_failover = nil        # -> (experiment, error) { ... }
-    config.on_adapter_failover = nil      # -> (adapter, error) { ... }
-
-    config.on_experiment_choose = nil     # -> (experiment, variant, metadata) { ... }
-    config.on_experiment_use = nil        # -> (experiment, variant, metadata) { ... }
-    config.on_experiment_convert = nil    # -> (experiment, variant, checkpoint, metadata) { ... }
-
-    config.on_experiment_start = nil      # -> (experiment) { ... }
-    config.on_experiment_stop = nil       # -> (experiment) { ... }
-    config.on_experiment_resume = nil     # -> (experiment) { ... }
-    config.on_experiment_reset = nil      # -> (experiment) { ... }
-    config.on_experiment_delete = nil     # -> (experiment) { ... }
-    config.on_experiment_winner = nil     # -> (experiment, winner) { ... }
-
-    config.return_experiment_winner = nil # -> (experiment, winner) { ... return variant }
-
-    config.filtered_user_agents = []
-    config.filtered_ip_addresses = []
-    config.request_filter = -> (context) do
-      is_preview? ||
-        is_filtered_user_agent? ||
-        is_filtered_ip_address?
-    end
-
-    def filtered_user_agents
-      @filtered_user_agents ||= begin
-        uas = @state[:filtered_user_agents]
-        uas = uas.call if uas.respond_to?(:call)
-        uas
-      end
-    end
-
-    def filtered_ip_addresses
-      @filtered_ip_addresses ||= begin
-        ips = @state[:filtered_ip_addresses]
-        ips = ips.call if ips.respond_to?(:call)
-        ips
-      end
-    end
-  end
-
-  def self.catalog
-    TrailGuide::Catalog.catalog
-  end
-
-  def self.redis
-    @redis ||= begin
-      if ['Redis', 'Redis::Namespace'].include?(configuration.redis.class.name)
-        configuration.redis
-      else
-        Redis.new(url: configuration.redis)
-      end
-    end
+  class << self
+    delegate :redis, to: :configuration
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailguide
 version: !ruby/object:Gem::Version
-  version: 0.1.17
+  version: 0.1.18
 platform: ruby
 authors:
 - Mark Rebec
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-08 00:00:00.000000000 Z
+date: 2019-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.3.6
+- !ruby/object:Gem::Dependency
+  name: redis-namespace
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -119,6 +133,7 @@ files:
 - app/views/trail_guide/admin/experiments/_experiment.html.erb
 - app/views/trail_guide/admin/experiments/index.html.erb
 - config/initializers/assets.rb
+- config/initializers/trailguide.rb
 - config/routes.rb
 - lib/trail_guide/adapters.rb
 - lib/trail_guide/adapters/participants.rb
@@ -137,6 +152,7 @@ files:
 - lib/trail_guide/algorithms/weighted.rb
 - lib/trail_guide/catalog.rb
 - lib/trail_guide/combined_experiment.rb
+- lib/trail_guide/config.rb
 - lib/trail_guide/engine.rb
 - lib/trail_guide/errors.rb
 - lib/trail_guide/experiment.rb