trailguide 0.1.0

data/lib/trail_guide/participant.rb

@@ -0,0 +1,110 @@
+module TrailGuide
+  class Participant
+    attr_reader :context
+    delegate :key?, :keys, :[], :[]=, :delete, :destroy!, :to_h, to: :adapter
+
+    def initialize(context, adapter: nil)
+      @context = context
+      @adapter = adapter.new(context) unless adapter.nil?
+    end
+
+    def adapter
+      @adapter ||= begin
+        config_adapter = TrailGuide.configuration.adapter
+        case config_adapter
+        when :cookie
+          config_adapter = TrailGuide::Adapters::Participants::Cookie
+        when :session
+          config_adapter = TrailGuide::Adapters::Participants::Session
+        when :redis
+          config_adapter = TrailGuide::Adapters::Participants::Redis
+        when :anonymous
+          config_adapter = TrailGuide::Adapters::Participants::Anonymous
+        when :multi
+          config_adapter = TrailGuide::Adapters::Participants::Multi
+        else
+          config_adapter = config_adapter.constantize if config_adapter.is_a?(String)
+        end
+        config_adapter.new(context)
+      end
+    end
+
+    def participating?(experiment, include_control=true)
+      return false unless adapter.key?(experiment.storage_key)
+      varname = adapter[experiment.storage_key]
+      variant = experiment.variants.find { |var| var == varname }
+      return false if !include_control && variant.control?
+      return false unless variant && adapter.key?(variant.storage_key)
+
+      chosen_at = Time.at(adapter[variant.storage_key].to_i)
+      chosen_at >= experiment.started_at
+    end
+
+    def converted?(experiment, checkpoint=nil)
+      if experiment.funnels.empty?
+        raise ArgumentError, "This experiment does not have any defined goal checkpoints" unless checkpoint.nil?
+        storage_key = "#{experiment.storage_key}:converted"
+        return false unless adapter.key?(storage_key)
+
+        converted_at = Time.at(adapter[storage_key].to_i)
+        converted_at >= experiment.started_at
+      elsif !checkpoint.nil?
+        raise ArgumentError, "Invalid goal checkpoint: #{checkpoint}" unless experiment.funnels.any? { |funnel| funnel == checkpoint.to_s.underscore.to_sym }
+        storage_key = "#{experiment.storage_key}:#{checkpoint.to_s.underscore}"
+        return false unless adapter.key?(storage_key)
+
+        converted_at = Time.at(adapter[storage_key].to_i)
+        converted_at >= experiment.started_at
+      else
+        experiment.funnels.each do |funnel|
+          storage_key = "#{experiment.storage_key}:#{funnel.to_s}"
+          next unless adapter.key?(storage_key)
+          converted_at = Time.at(adapter[storage_key].to_i)
+          return true if converted_at >= experiment.started_at
+        end
+        return false
+      end
+    end
+
+    def participating!(variant)
+      adapter[variant.experiment.storage_key] = variant.name
+      adapter[variant.storage_key] = Time.now.to_i
+    end
+
+    def converted!(variant, checkpoint=nil, reset: false)
+      checkpoint ||= :converted
+      storage_key = "#{variant.experiment.storage_key}:#{checkpoint.to_s.underscore}"
+
+      if reset
+        adapter.delete(variant.experiment.storage_key)
+        adapter.delete(variant.storage_key)
+        adapter.delete(storage_key)
+        experiment.funnels.each do |funnel|
+          funnel_key = "#{variant.experiment.storage_key}:#{funnel.to_s}"
+          adapter.delete(funnel_key)
+        end
+      else
+        adapter[storage_key] = Time.now.to_i
+      end
+    end
+
+    def active_experiments(include_control=true)
+      return false if adapter.keys.empty?
+      adapter.keys.map { |key| key.to_s.split(":").first.to_sym }.uniq.map do |key|
+        experiment = TrailGuide.catalog.find(key)
+        next unless experiment && experiment.started? && participating?(experiment, include_control)
+        [ experiment.experiment_name, adapter[experiment.storage_key] ]
+      end.compact.to_h
+    end
+
+    def participating_in_active_experiments?(include_control=true)
+      return false if adapter.keys.empty?
+
+      adapter.keys.any? do |key|
+        experiment_name = key.to_s.split(":").first.to_sym
+        experiment = TrailGuide.catalog.find(experiment_name)
+        experiment && experiment.started? && participating?(experiment, include_control)
+      end
+    end
+  end
+end

data/lib/trail_guide/unity.rb

@@ -0,0 +1,87 @@
+module TrailGuide
+  class Unity
+    NAMESPACE = :unity
+
+    def self.clear!
+      keys = TrailGuide.redis.keys("#{NAMESPACE}:*")
+      TrailGuide.redis.del *keys unless keys.empty?
+    end
+
+    attr_reader :visitor_id, :user_id
+
+    def initialize(user_id: nil, visitor_id: nil)
+      @user_id = user_id.to_s if user_id.present?
+      @visitor_id = visitor_id.to_s if visitor_id.present?
+    end
+
+    def user_id=(uid)
+      @user_id = uid.to_s
+    end
+
+    def visitor_id=(vid)
+      @visitor_id = vid.to_s
+    end
+
+    def stored_user_id
+      TrailGuide.redis.get(visitor_key) if visitor_id.present?
+    end
+
+    def stored_visitor_id
+      TrailGuide.redis.get(user_key) if user_id.present?
+    end
+
+    def valid?
+      visitor_id.present? && user_id.present?
+    end
+
+    def stored?
+      stored_visitor_id.present? && stored_user_id.present?
+    end
+
+    def synced?
+      valid? && stored? && 
+        stored_visitor_id == visitor_id &&
+        stored_user_id == user_id
+    end
+
+    def sync!
+      @user_id ||= stored_user_id
+      @visitor_id ||= stored_visitor_id
+      delete!
+      save!
+    end
+
+    def save!
+      return false unless valid?
+      TrailGuide.redis.set(user_key, visitor_id)
+      TrailGuide.redis.set(visitor_key, user_id)
+    end
+
+    def delete!
+      keys = []
+      keys << stored_user_key if stored_user_id.present?
+      keys << stored_visitor_key if stored_visitor_id.present?
+      keys << user_key if user_id.present?
+      keys << visitor_key if visitor_id.present?
+      TrailGuide.redis.del(*keys) unless keys.empty?
+    end
+
+    protected
+
+    def user_key
+      "#{NAMESPACE}:uids:#{user_id}"
+    end
+
+    def visitor_key
+      "#{NAMESPACE}:vids:#{visitor_id}"
+    end
+
+    def stored_user_key
+      "#{NAMESPACE}:uids:#{stored_user_id}"
+    end
+
+    def stored_visitor_key
+      "#{NAMESPACE}:vids:#{stored_visitor_id}"
+    end
+  end
+end

data/lib/trail_guide/variant.rb

@@ -0,0 +1,103 @@
+module TrailGuide
+  class Variant
+    attr_reader :experiment, :name, :metadata, :weight
+
+    def initialize(experiment, name, metadata: {}, weight: 1, control: false)
+      @experiment = experiment
+      @name = name.to_s.underscore.to_sym
+      @metadata = metadata
+      @weight = weight
+      @control = control
+    end
+
+    def ==(other)
+      if other.is_a?(self.class)
+        return name == other.name && experiment == other.experiment
+      elsif other.is_a?(String) || other.is_a?(Symbol)
+        return name == other.to_s.underscore.to_sym
+      end
+    end
+
+    # TODO maybe track the control on the experiment itself, rather than as a
+    # flag on the variants like this?
+
+    # mark this variant as the control
+    def control!
+      @control = true
+    end
+
+    # check if this variant is the control
+    def control?
+      !!@control
+    end
+
+    # unmark this variant as the control
+    def variant!
+      @control = false
+    end
+
+    def persisted?
+      TrailGuide.redis.exists(storage_key)
+    end
+
+    def save!
+      TrailGuide.redis.hsetnx(storage_key, 'name', name)
+    end
+
+    def delete!
+      TrailGuide.redis.del(storage_key)
+    end
+
+    def reset!
+      delete! && save!
+    end
+
+    def participants
+      (TrailGuide.redis.hget(storage_key, 'participants') || 0).to_i
+    end
+
+    def converted(checkpoint=nil)
+      if experiment.funnels.empty?
+        raise ArgumentError, "This experiment does not have any defined goal checkpoints" unless checkpoint.nil?
+        (TrailGuide.redis.hget(storage_key, 'converted') || 0).to_i
+      elsif !checkpoint.nil?
+        raise ArgumentError, "Invalid goal checkpoint: #{checkpoint}" unless experiment.funnels.any? { |funnel| funnel == checkpoint.to_s.underscore.to_sym }
+        (TrailGuide.redis.hget(storage_key, checkpoint.to_s.underscore) || 0).to_i
+      else
+        experiment.funnels.sum do |checkpoint|
+          (TrailGuide.redis.hget(storage_key, checkpoint.to_s.underscore) || 0).to_i
+        end
+      end
+    end
+
+    def unconverted
+      participants - converted
+    end
+
+    def increment_participation!
+      TrailGuide.redis.hincrby(storage_key, 'participants', 1)
+    end
+
+    def increment_conversion!(checkpoint=nil)
+      checkpoint ||= :converted
+      TrailGuide.redis.hincrby(storage_key, checkpoint.to_s.underscore, 1)
+    end
+
+    def as_json(opts={})
+      {
+        name: name,
+        control: control?,
+        weight: weight,
+        metadata: metadata.as_json,
+      }
+    end
+
+    def to_s
+      name.to_s
+    end
+
+    def storage_key
+      "#{experiment.experiment_name}:#{name}"
+    end
+  end
+end

data/lib/trail_guide/version.rb

@@ -0,0 +1,14 @@
+module TrailGuide
+  module Version
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+    VERSION = "#{MAJOR}.#{MINOR}.#{PATCH}"
+
+    class << self
+      def inspect
+        VERSION
+      end
+    end
+  end
+end

data/lib/trailguide.rb

@@ -0,0 +1,57 @@
+require "canfig"
+require "redis"
+require "trail_guide/adapters"
+require "trail_guide/algorithms"
+require "trail_guide/participant"
+require "trail_guide/variant"
+require "trail_guide/experiment"
+require "trail_guide/catalog"
+require "trail_guide/helper"
+require "trail_guide/engine"
+
+module TrailGuide
+  include Canfig::Module
+
+  configure do |config|
+    config.redis = ENV['REDIS_URL']
+    config.disabled = false
+    config.start_manually = true
+    config.reset_manually = true
+    config.store_override = false
+    config.override_parameter = :experiment
+    config.allow_multiple_experiments = true # false / :control
+    config.algorithm = :weighted
+    config.adapter = :multi
+
+    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_reset = nil   # -> (experiment) { ... }
+    config.on_experiment_delete = nil  # -> (experiment) { ... }
+
+    config.filtered_user_agents = []
+    config.filtered_ip_addresses = []
+    config.request_filter = -> (context) do
+      is_preview? ||
+        is_filtered_user_agent? ||
+        is_filtered_ip_address?
+    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
+  end
+end

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification
+name: trailguide
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mark Rebec
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-03-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: canfig
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.7
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simple-random
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.3
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.6
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  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'
+description: Perform user experiments and A/B tests in your rails apps
+email:
+- mark@markrebec.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- config/routes.rb
+- lib/trail_guide/adapters.rb
+- lib/trail_guide/adapters/participants.rb
+- lib/trail_guide/adapters/participants/anonymous.rb
+- lib/trail_guide/adapters/participants/cookie.rb
+- lib/trail_guide/adapters/participants/multi.rb
+- lib/trail_guide/adapters/participants/redis.rb
+- lib/trail_guide/adapters/participants/session.rb
+- lib/trail_guide/adapters/participants/unity.rb
+- lib/trail_guide/algorithms.rb
+- lib/trail_guide/algorithms/bandit.rb
+- lib/trail_guide/algorithms/distributed.rb
+- lib/trail_guide/algorithms/random.rb
+- lib/trail_guide/algorithms/weighted.rb
+- lib/trail_guide/catalog.rb
+- lib/trail_guide/engine.rb
+- lib/trail_guide/experiment.rb
+- lib/trail_guide/helper.rb
+- lib/trail_guide/participant.rb
+- lib/trail_guide/unity.rb
+- lib/trail_guide/variant.rb
+- lib/trail_guide/version.rb
+- lib/trailguide.rb
+homepage: https://github.com/markrebec/trailguide
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: User experiments for rails
+test_files: []