tupalo-vanity 1.5.1

data/bin/vanity

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# Is there a better way to detect Rails?
+if File.exist?("config/boot.rb") && File.exist?("config/environment.rb")
+  require "config/environment"
+else
+  path = File.expand_path("../lib", File.dirname(__FILE__))
+  $LOAD_PATH.unshift path unless $LOAD_PATH.include?(path)
+  require "vanity"
+end
+
+require "optparse"
+
+playground = Vanity.playground
+options = Struct.new(:output).new
+opts = OptionParser.new("", 24, "  ") do |opts|
+  opts.banner = "Usage: #{File.basename($0)} [options] command\n"
+  opts.banner << "Commands:\n"
+  opts.banner << "  list    List all experiments and metrics\n"
+  opts.banner << "  report  Report on all running experiments/metrics\n"
+  opts.banner << "  upgrade Upgrade your database when deploying new release\n"
+
+  opts.separator ""
+  opts.separator "Reporting options:"
+  opts.on "--output FILE", "Write report to this file (default: stdout)" do |path|
+    options.output = path
+  end
+
+  opts.separator ""
+  opts.separator "Common options:"
+  opts.on "--load_path PATH", "Path to experiments directory (default: #{playground.load_path})" do |path|
+    playground.load_path = path
+  end
+  opts.on "-d", "--database url", "Database connection URL (e.g. redis:/localhost:6379)" do |conn|
+    playground.establish_connection conn
+  end
+  opts.on "--redis HOST:PORT:DB", "DEPRECATED: Redis server host (default: localhost:6379)" do |redis|
+    host, port, db = redis.split(":")
+    playground.establish_connection "redis:/#{host}:#{port}/#{db}"
+  end
+  opts.on_tail "-h", "--help", "Show this message" do
+    puts opts.to_s.gsub(/^.*DEPRECATED.*$/s, '')
+    exit
+  end
+  opts.on_tail "-v", "--version", "Show version"  do
+    puts "Vanity #{Vanity::Version::STRING}"
+    exit
+  end
+end
+
+opts.parse!(ARGV)
+if ARGV.empty?
+  puts opts.banner
+  exit
+end
+
+ARGV.each do |cmd|
+  case cmd
+  when "report"
+    require "vanity/commands/report"
+    Vanity::Commands.report options.output
+  when "list"
+    require "vanity/commands/list"
+    Vanity::Commands.list
+  when "upgrade"
+    require "vanity/commands/upgrade"
+    Vanity::Commands.upgrade
+  else fail "No such command: #{cmd}"
+  end
+end

data/lib/vanity.rb

@@ -0,0 +1,36 @@
+require "date"
+require "time"
+require "logger"
+require "cgi"
+require "erb"
+require "yaml"
+
+# All the cool stuff happens in other places.
+# @see Vanity::Helper
+# @see Vanity::Rails
+# @see Vanity::Playground
+# @see Vanity::Metric
+# @see Vanity::Experiment
+module Vanity
+end
+
+require "vanity/version"
+require "vanity/backport" if RUBY_VERSION < "1.9"
+# Metrics.
+require "vanity/metric/base"
+require "vanity/metric/active_record"
+require "vanity/metric/google_analytics"
+require "vanity/metric/remote"
+# Experiments.
+require "vanity/experiment/base"
+require "vanity/experiment/ab_test"
+# Database adapters
+require "vanity/adapters/abstract_adapter"
+require "vanity/adapters/redis_adapter"
+require "vanity/adapters/mongodb_adapter"
+require "vanity/adapters/mock_adapter"
+# Playground.
+require "vanity/playground"
+require "vanity/helpers"
+# Integration with various frameworks.
+require "vanity/frameworks/rails" if defined?(Rails)

data/lib/vanity/adapters/abstract_adapter.rb

@@ -0,0 +1,135 @@
+module Vanity
+  module Adapters
+
+    class << self
+      # Creates new connection to underlying datastore and returns suitable
+      # adapter (adapter object extends AbstractAdapter and wraps the
+      # connection). Vanity.playgroup.establish_connection uses this.
+      #
+      # @since 1.4.0
+      def establish_connection(spec)
+        adapter_method = "#{spec[:adapter]}_connection"
+        send adapter_method, spec
+      end
+    end
+
+    # Base class for all adapters. Adapters wrap underlying connection to a
+    # datastore and implement an API that Vanity can use to store/access
+    # metrics, experiments, etc.
+    class AbstractAdapter
+      # Returns true if connected.
+      def active?
+        false
+      end
+
+      # Close connection, release any resources.
+      def disconnect!
+      end
+
+      # Close and reopen connection.
+      def reconnect!
+      end
+
+      # Empty the database. This is used during tests.
+      def flushdb
+      end
+      
+
+      # -- Metrics --
+     
+      # Return when metric was last updated.
+      def get_metric_last_update_at(metric)
+        fail "Not implemented"
+      end
+  
+      # Track metric data.
+      def metric_track(metric, timestamp, identity, values)
+        fail "Not implemented"
+      end
+
+      # Returns all the metric values between from and to time instances
+      # (inclusive). Returns pairs of date and total count for that date.
+      def metric_values(metric, from, to)
+        fail "Not implemented"
+      end
+
+      # Deletes all information about this metric.
+      def destroy_metric(metric)
+        fail "Not implemented"
+      end
+
+
+      # -- Experiments --
+
+      # Store when experiment was created (do not write over existing value). 
+      def set_experiment_created_at(experiment, time)
+        fail "Not implemented"
+      end
+
+      # Return when experiment was created.
+      def get_experiment_created_at(experiment)
+        fail "Not implemented"
+      end
+     
+      # Returns true if experiment completed. 
+      def is_experiment_completed?(experiment)
+        fail "Not implemented"
+      end
+
+      # Returns counts for given A/B experiment and alternative (by index).
+      # Returns hash with values for the keys :participants, :converted and
+      # :conversions.
+      def ab_counts(experiment, alternative)
+        fail "Not implemented"
+      end 
+
+      # Pick particular alternative (by index) to show to this particular
+      # participant (by identity).
+      def ab_show(experiment, identity, alternative)
+        fail "Not implemented"
+      end
+
+      # Indicates which alternative to show to this participant. See #ab_show.
+      def ab_showing(experiment, identity)
+        fail "Not implemented"
+      end
+
+      # Cancels previously set association between identity and alternative. See
+      # #ab_show.
+      def ab_not_showing(experiment, identity)
+        fail "Not implemented"
+      end
+
+      # Records a participant in this experiment for the given alternative.
+      def ab_add_participant(experiment, alternative, identity)
+        fail "Not implemented"
+      end
+
+      # Records a conversion in this experiment for the given alternative.
+      # Associates a value with the conversion (default to 1). If implicit is
+      # true, add particpant if not already recorded for this experiment. If
+      # implicit is false (default), only add conversion is participant
+      # previously recorded as participating in this experiment.
+      def ab_add_conversion(experiment, alternative, identity, count = 1, implicit = false)
+        fail "Not implemented"
+      end
+
+      # Returns the outcome of this expriment (if set), the index of a
+      # particular alternative.
+      def ab_get_outcome(experiment)
+        fail "Not implemented"
+      end
+
+      # Sets the outcome of this experiment to a particular alternative.
+      def ab_set_outcome(experiment, alternative = 0)
+        fail "Not implemented"
+      end
+
+      # Deletes all information about this experiment.
+      def destroy_experiment(experiment)
+        fail "Not implemented"
+      end
+
+    end
+  end
+end

data/lib/vanity/adapters/active_record_adapter.rb

@@ -0,0 +1,304 @@
+module Vanity
+  module Adapters
+    class << self
+      # Creates new ActiveRecord connection and returns ActiveRecordAdapter.
+      def active_record_connection(spec)
+        require 'active_record'
+        ActiveRecordAdapter.new(spec)
+      end
+    end
+
+    # ActiveRecord adapter
+    class ActiveRecordAdapter < AbstractAdapter
+      # Base model, stores connection and defines schema
+      class VanityRecord < ActiveRecord::Base
+        def self.define_schema
+          # Create a schema table to store the schema version
+          unless connection.tables.include?('vanity_schema')
+            connection.create_table :vanity_schema do |t|
+              t.integer :version
+            end
+          end
+
+          # Migrate
+          unless VanitySchema.find_by_version(1)
+            connection.create_table :vanity_metrics do |t|
+              t.string :metric_id
+              t.datetime :updated_at
+            end
+            connection.add_index :vanity_metrics, [:metric_id]
+
+            connection.create_table :vanity_metric_values do |t|
+              t.integer :vanity_metric_id
+              t.integer :index
+              t.integer :value
+              t.string :date
+            end
+            connection.add_index :vanity_metric_values, [:vanity_metric_id]
+
+            connection.create_table :vanity_experiments do |t|
+              t.string :experiment_id
+              t.integer :outcome
+              t.datetime :created_at
+              t.datetime :completed_at
+            end
+            connection.add_index :vanity_experiments, [:experiment_id]
+
+            connection.create_table :vanity_conversions do |t|
+              t.integer :vanity_experiment_id
+              t.integer :alternative
+              t.integer :conversions
+            end
+            connection.add_index :vanity_conversions, [:vanity_experiment_id, :alternative]
+
+            connection.create_table :vanity_participants do |t|
+              t.string :experiment_id
+              t.string :identity
+              t.integer :shown
+              t.integer :seen
+              t.integer :converted
+            end
+            connection.add_index :vanity_participants, [:experiment_id]
+            connection.add_index :vanity_participants, [:experiment_id, :identity]
+            connection.add_index :vanity_participants, [:experiment_id, :shown]
+            connection.add_index :vanity_participants, [:experiment_id, :seen]
+            connection.add_index :vanity_participants, [:experiment_id, :converted]
+
+            VanitySchema.create(:version => 1)
+          end
+        end
+      end
+
+      # Schema model
+      class VanitySchema < VanityRecord
+        set_table_name :vanity_schema
+      end
+
+      # Metric model
+      class VanityMetric < VanityRecord
+        set_table_name :vanity_metrics
+        has_many :vanity_metric_values
+
+        def self.retrieve(metric)
+          find_or_create_by_metric_id(metric.to_s)
+        end
+      end
+
+      # Metric value
+      class VanityMetricValue < VanityRecord
+        set_table_name :vanity_metric_values
+        belongs_to :vanity_metric
+      end
+
+      # Experiment model
+      class VanityExperiment < VanityRecord
+        set_table_name :vanity_experiments
+        has_many :vanity_conversions, :dependent => :destroy
+
+        # Finds or creates the experiment
+        def self.retrieve(experiment)
+          find_or_create_by_experiment_id(experiment.to_s)
+        end
+
+        def increment_conversion(alternative, count = 1)
+          record = vanity_conversions.find_or_create_by_alternative(alternative)
+          record.increment!(:conversions, count)
+        end
+      end
+
+      # Conversion model
+      class VanityConversion < VanityRecord
+        set_table_name :vanity_conversions
+        belongs_to :vanity_experiment
+      end
+
+      # Participant model
+      class VanityParticipant < VanityRecord
+        set_table_name :vanity_participants
+
+        # Finds the participant by experiment and identity. If
+        # create is true then it will create the participant
+        # if not found. If a hash is passed then this will be
+        # passed to create if creating, or will be used to
+        # update the found participant.
+        def self.retrieve(experiment, identity, create = true, update_with = nil)
+          record = VanityParticipant.first(
+                  :conditions =>
+                          {:experiment_id => experiment.to_s, :identity => identity})
+
+          if record
+            record.update_attributes(update_with) if update_with
+          elsif create
+            record = VanityParticipant.create(
+                    {:experiment_id => experiment.to_s,
+                     :identity => identity}.merge(update_with || {}))
+          end
+
+          record
+        end
+      end
+
+      def initialize(options)
+        options[:adapter] = options[:active_record_adapter] if options[:active_record_adapter]
+
+        VanityRecord.establish_connection(options)
+        VanityRecord.define_schema
+      end
+
+      def active?
+        VanityRecord.connected?
+      end
+
+      def disconnect!
+        VanityRecord.connection.disconnect! if active?
+      end
+
+      def reconnect!
+        VanityRecord.connection.reconnect!
+      end
+
+      def flushdb
+        [VanityExperiment, VanityMetric, VanityParticipant, VanityMetricValue, VanityConversion].each do |klass|
+          klass.delete_all
+        end
+      end
+
+      def get_metric_last_update_at(metric)
+        record = VanityMetric.find_by_metric_id(metric.to_s)
+        record && record.updated_at
+      end
+
+      def metric_track(metric, timestamp, identity, values)
+        record = VanityMetric.retrieve(metric)
+
+        values.each_with_index do |value, index|
+          record.vanity_metric_values.create(:date => timestamp.to_date.to_s, :index => index, :value => value)
+        end
+
+        record.updated_at = Time.now
+        record.save
+      end
+
+      def metric_values(metric, from, to)
+        connection = VanityMetric.connection
+        record = VanityMetric.retrieve(metric)
+        dates = (from.to_date..to.to_date).map(&:to_s)
+        conditions = [connection.quote_column_name('date') + ' IN (?)', dates]
+        order = "#{connection.quote_column_name('date')}"
+        select = "sum(#{connection.quote_column_name('value')}) value, #{connection.quote_column_name('date')}"
+        group_by = "#{connection.quote_column_name('date')}"
+
+        values = record.vanity_metric_values.all(
+                :select => select,
+                :conditions => conditions,
+                :order => order,
+                :group => group_by
+        )
+
+        dates.map do |date|
+          value = values.detect{|v| v.date == date }
+          [(value && value.value) || 0]
+        end
+      end
+
+      def destroy_metric(metric)
+        record = VanityMetric.find_by_metric_id(metric.to_s)
+        record && record.destroy
+      end
+
+      # Store when experiment was created (do not write over existing value).
+      def set_experiment_created_at(experiment, time)
+        record = VanityExperiment.find_by_experiment_id(experiment.to_s) ||
+                VanityExperiment.new(:experiment_id => experiment.to_s)
+        record.created_at ||= time
+        record.save
+      end
+
+      # Return when experiment was created.
+      def get_experiment_created_at(experiment)
+        record = VanityExperiment.retrieve(experiment)
+        record && record.created_at
+      end
+
+      def set_experiment_completed_at(experiment, time)
+        VanityExperiment.retrieve(experiment).update_attribute(:completed_at, time)
+      end
+
+      def get_experiment_completed_at(experiment)
+        VanityExperiment.retrieve(experiment).completed_at
+      end
+
+      # Returns true if experiment completed.
+      def is_experiment_completed?(experiment)
+        !!VanityExperiment.retrieve(experiment).completed_at
+      end
+
+      # Returns counts for given A/B experiment and alternative (by index).
+      # Returns hash with values for the keys :participants, :converted and
+      # :conversions.
+      def ab_counts(experiment, alternative)
+        record = VanityExperiment.retrieve(experiment)
+        participants = VanityParticipant.count(:conditions => {:experiment_id => experiment.to_s, :seen => alternative})
+        converted = VanityParticipant.count(:conditions => {:experiment_id => experiment.to_s, :converted => alternative})
+        conversions = record.vanity_conversions.sum(:conversions, :conditions => {:alternative => alternative})
+
+        {
+                :participants => participants,
+                :converted => converted,
+                :conversions => conversions
+        }
+      end
+
+      # Pick particular alternative (by index) to show to this particular
+      # participant (by identity).
+      def ab_show(experiment, identity, alternative)
+        VanityParticipant.retrieve(experiment, identity, true, :shown => alternative)
+      end
+
+      # Indicates which alternative to show to this participant. See #ab_show.
+      def ab_showing(experiment, identity)
+        participant = VanityParticipant.retrieve(experiment, identity, false)
+        participant && participant.shown
+      end
+
+      # Cancels previously set association between identity and alternative. See
+      # #ab_show.
+      def ab_not_showing(experiment, identity)
+        VanityParticipant.retrieve(experiment, identity, true, :shown => nil)
+      end
+
+      # Records a participant in this experiment for the given alternative.
+      def ab_add_participant(experiment, alternative, identity)
+        VanityParticipant.retrieve(experiment, identity, true, :seen => alternative)
+      end
+
+      # Records a conversion in this experiment for the given alternative.
+      # Associates a value with the conversion (default to 1). If implicit is
+      # true, add particpant if not already recorded for this experiment. If
+      # implicit is false (default), only add conversion is participant
+      # previously recorded as participating in this experiment.
+      def ab_add_conversion(experiment, alternative, identity, count = 1, implicit = false)
+        VanityParticipant.retrieve(experiment, identity, implicit, :converted => alternative)
+        VanityExperiment.retrieve(experiment).increment_conversion(alternative, count)
+      end
+
+      # Returns the outcome of this experiment (if set), the index of a
+      # particular alternative.
+      def ab_get_outcome(experiment)
+        VanityExperiment.retrieve(experiment).outcome
+      end
+
+      # Sets the outcome of this experiment to a particular alternative.
+      def ab_set_outcome(experiment, alternative = 0)
+        VanityExperiment.retrieve(experiment).update_attribute(:outcome, alternative)
+      end
+
+      # Deletes all information about this experiment.
+      def destroy_experiment(experiment)
+        VanityParticipant.delete_all(:experiment_id => experiment.to_s)
+        record = VanityExperiment.find_by_experiment_id(experiment.to_s)
+        record && record.destroy
+      end
+    end
+  end
+end