divisio 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8aae102437166c67d6dc2dfe8277969afee58978
+  data.tar.gz: 34d89f2cf876329fa57d519c1ee76cdd17d6666f
+SHA512:
+  metadata.gz: afa5878c8dae28f8848b3f095fe55240931c4b21711109bd033e3761d40934ae7c292f76d201c87ddb5b40809c2467fb973c071499eb8eacd48731e33936555c
+  data.tar.gz: 9822d1d7741be88a91cb1725be4af78eb343b34c5f2481559763fb1099ef5f6b5dcd326a57f16ff0f7bc7126133e2e42a2467c7fd494e0f200fcb2e6cc5c5771

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,4 @@
+--order rand
+--color
+--require spec_helper
+--format doc

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in divisio.gemspec
+gemspec
+
+group :development, :test do
+  gem 'pry-plus'
+  gem 'mongoid'
+end
+
+group :test do
+  gem 'rspec'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Simply Business
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# Divisio
+
+This gem assigns identities to a variant inside an experiment. It is similar to ab-tests framework.
+
+A triplet - experiment, variants and identities will always produce the same variant outcome even if the test is deleted and rerun.
+
+You can run multiple instances of the framework inside the same application for different adapters.
+
+You can use it wherever you want however you want (you can make a global object for entire application or you can make individual little objects to be used inside methods).
+It is up to you do decide!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'divisio'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install divisio
+
+## Usage
+
+### No persistence adapter
+
+_This is the default adapter_
+
+It returns the selected variant, but does not persist any information.
+
+```ruby
+experiment_name = 'experiment1'
+variants        = [1,2,3]
+identity        = 'dragos'
+
+Divisio.new.split(experiment_name, variants, identity) # ==>> 1
+```
+
+### Mongoid adaper
+
+_Requires mongoid v4.0.0 or greater_
+
+This adapter will persist the experiment name, identifier, and variant information in a MongoDb collection called `experiments`. Note: The variant returned will be cast to a string.
+
+```ruby
+experiment_name = 'experiment1'
+variants        = [1,2,3]
+identity        = 'dragos'
+
+Divisio.new(adapter: Divisio::MongoidAdapter).split(experiment_name, variants, identity) # ==>> '1'
+```
+
+You can also specify the default adapter in your initializers as so:
+
+```ruby
+Divisio.default_adapter = Divisio::MongoidAdapter
+```
+
+then
+
+```ruby
+Divisio.new.split(experiment_name, variants, identity) # ==>> '1'
+```
+
+### Weighted variants
+
+Variants can be weighted by passing a hash of variants mapped to their relative weights, for example:
+
+```ruby
+experiment_name = 'experiment1'
+variants        = { a: 1, b: 2, c: 3 }
+identity        = 'dragos'
+
+Divisio.new.split(experiment_name, variants, identity) # ==>> :c
+```
+
+There are three variants in this example: `a`, `b`, `c`
+
+Variant `a` has a weight of 1, `b` has a weight of 2, `c` has a weight of 3.
+
+Effectively, this means that the chances of getting the variant `b` are twice a likely as getting the variant `a`. The chances of getting the variant `c` are thrice as likely as getting the variant `a`.
+
+### Further examples
+
+You can use what it returns *directly*, for example if you want to render a partial you could do:
+
+```ruby
+partial = Divisio.new.split('amazing partial', ['partial1', 'partial2'], identity)
+render(partial)
+```
+
+If we want to do complex logic based on some idiom, you need to do if/case statements:
+
+```ruby
+# this method could be in a global helper
+def enable_partial_quotes
+  decision = Divisio.new.split('enable_partial_quotes', ['yes', 'no'], identity)
+  decision == 'yes'
+end
+
+# .....
+# then somewhere else
+# .....
+if enable_partial_quotes
+  # do some stuff
+else
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/divisio/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/divisio.gemspec

@@ -0,0 +1,20 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'divisio/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'divisio'
+  spec.version       = Divisio::VERSION
+  spec.authors       = ['Dragos Miron']
+  spec.email         = ['tech@simplybusiness.co.uk']
+  spec.summary       = %q{Provides a splitting framework similar to AB testing}
+  spec.description   = %q{Provides a splitting framework similar to AB testing}
+  spec.homepage      = 'http://www.simplybusiness.co.uk'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+end

data/lib/divisio.rb

@@ -0,0 +1,27 @@
+require 'divisio/base_adapter'
+require 'divisio/no_persistence_adapter'
+require 'divisio/modulo_algorithm'
+require 'divisio/mongoid_adapter' if defined? Mongoid
+
+class Divisio
+
+  @default_adapter = Divisio::NoPersistenceAdapter
+  class << self
+    attr_accessor :default_adapter
+  end
+
+  attr_reader :adapter
+  private :adapter
+
+  def initialize(adapter: self.class.default_adapter)
+    @adapter = adapter
+  end
+
+  def split(experiment_name, variants, identity)
+    adapter.split(experiment_name, variants, identity)
+  end
+
+  def delete_experiment_for_identity(identity, experiment_name)
+    adapter.delete_experiment_for_identity(identity, experiment_name)
+  end
+end

data/lib/divisio/base_adapter.rb

@@ -0,0 +1,13 @@
+class Divisio
+  module BaseAdapter
+    extend self
+
+    def split(experiment_name, variants, identity)
+      ModuloAlgorithm.new(experiment_name.to_s+identity.to_s, variants).calc
+    end
+
+    def delete_experiment_for_identity(identity, experiment_name)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/divisio/modulo_algorithm.rb

@@ -0,0 +1,30 @@
+class Divisio
+  class ModuloAlgorithm
+
+    attr_reader :key, :variants
+    private :key, :variants
+
+    def initialize(key, variants)
+      @key      = key.to_s
+      @variants = variants_as_array(variants)
+    end
+
+    def calc
+      number_of_variants = variants.size
+      position           = Digest::MD5.hexdigest(key).to_i(16) % number_of_variants
+
+      variants[position]
+    end
+
+    private
+
+    def variants_as_array(variants)
+      return Array(variants) unless variants.is_a? Hash
+      flattened_variants = []
+      variants.each_pair do |name, weight|
+        weight.times { flattened_variants << name }
+      end
+      flattened_variants
+    end
+  end
+end

data/lib/divisio/mongoid_adapter.rb

@@ -0,0 +1,29 @@
+%w(experiment).each do |f|
+  require_relative "mongoid_adapter/#{f}"
+end
+
+class Divisio
+  module MongoidAdapter
+    include BaseAdapter
+    extend self
+
+    def split(experiment_name, variants, identity)
+      experiment_object = Experiment.where(identifier: identity, name: experiment_name).first
+      return experiment_object.variant if experiment_object
+
+      variant_for_identity = super.to_s
+      experiment_object = Experiment.new(identifier: identity, name: experiment_name, variant: variant_for_identity)
+
+      return variant_for_identity if experiment_object.save
+    rescue Moped::Errors::OperationFailure
+      split(experiment_name, variants, identity)
+    end
+
+    def delete_experiment_for_identity(identity, experiment_name)
+      experiment_object = Experiment.where(identifier: identity, name: experiment_name).first
+
+      return experiment_object.destroy if experiment_object
+      return false
+    end
+  end
+end

data/lib/divisio/mongoid_adapter/experiment.rb

@@ -0,0 +1,19 @@
+class Divisio
+  module MongoidAdapter
+    class Experiment
+
+      include Mongoid::Document
+      include Mongoid::Timestamps
+
+      validates_presence_of :name, :variant, :identifier
+      validates_uniqueness_of :identifier, scope: :name
+
+      field :name, type: String
+      field :identifier, type: String
+      field :variant, type: String
+
+      index({ name: 1, identifier: 1}, { unique: true})
+
+    end
+  end
+end

data/lib/divisio/no_persistence_adapter.rb

@@ -0,0 +1,6 @@
+class Divisio
+  module NoPersistenceAdapter
+    include BaseAdapter
+    extend self
+  end
+end

data/lib/divisio/version.rb

@@ -0,0 +1,3 @@
+class Divisio
+  VERSION = '0.1.0'
+end

data/mongoid.yml

@@ -0,0 +1,8 @@
+test:
+  sessions:
+    default:
+      database: divisio_test
+      hosts:
+        - localhost:27017
+      options:
+        <%= "safe: true" if Mongoid::VERSION =~ /^3/%>

data/spec/divisio/base_adapter_spec.rb

@@ -0,0 +1,4 @@
+describe Divisio::BaseAdapter do
+
+  it_behaves_like 'a base adapter'
+end

data/spec/divisio/modulo_algorithm_spec.rb

@@ -0,0 +1,33 @@
+describe Divisio::ModuloAlgorithm do
+  describe '#calc' do
+    let(:variants) {  }
+
+    context 'when there is one variant provided' do
+      let(:variants) { 1 }
+
+      it 'returns the variant' do
+        expect(Divisio::ModuloAlgorithm.new('key', variants).calc).to eq(1)
+      end
+    end
+
+    context 'when there are multiple variants provided' do
+      let(:variants) { ['1', '2', '3'] }
+
+      { blah8: '1', blah4: '2', blah0: '3'}.each_pair do |key, expected_variant|
+        it "returns the variant based on the key provided: #{key}" do
+          expect(Divisio::ModuloAlgorithm.new(key, variants).calc).to eq(expected_variant)
+        end
+      end
+    end
+
+    context 'when there are multiple weighted variants provided' do
+      let(:variants) { { a: 1, b: 2, c: 3 } }
+
+      { blah8: :a, blah4: :b, blah0: :c}.each_pair do |key, expected_variant|
+        it "returns the variant based on the key provided and weight: #{key}" do
+          expect(Divisio::ModuloAlgorithm.new(key, variants).calc).to eq(expected_variant)
+        end
+      end
+    end
+  end
+end

data/spec/divisio/mongoid_adapter/experiment_spec.rb

@@ -0,0 +1,55 @@
+describe Divisio::MongoidAdapter::Experiment do
+  describe '#save' do
+
+    let(:required_fields) { {:name => 'experiment', :identifier => 'hash', :variant => '2'} }
+    subject { Divisio::MongoidAdapter::Experiment.new }
+
+    context 'all fields are present' do
+      it 'gets saved to the database' do
+        subject.attributes = required_fields
+
+        expect{ subject.save }.to change{ described_class.count }.from(0).to(1)
+      end
+    end
+
+    context 'missing fields' do
+      it 'does not get saved if identifier is missing' do
+        subject.attributes = required_fields.tap{ |h| h.delete(:identifier) }
+        expect(subject.save).to be_falsey
+      end
+
+      it 'does not get saved if name is missing' do
+        subject.attributes = required_fields.tap{ |h| h.delete(:name) }
+        expect(subject.save).to be_falsey
+      end
+
+      it 'does not get saved if variant is missing' do
+        subject.attributes = required_fields.tap{ |h| h.delete(:variant) }
+        expect(subject.save).to be_falsey
+      end
+    end
+
+    context 'uniqueness' do
+
+      it 'does not save second object with the same name and identifier' do
+        subject.attributes = required_fields
+        subject.save
+        expect(described_class.count).to eq(1)
+
+        required_fields[:variant] = '3'
+        new_object = described_class.new(required_fields)
+
+        expect{ new_object.save }.to_not change(described_class, :count)
+      end
+
+      it 'does not save second object in case of race condition because of mongo index' do
+        described_class.create_indexes
+        Mongoid.default_session[:divisio_mongoid_adapter_experiments].insert(required_fields)
+        expect(described_class.count).to eq(1)
+
+        collection = described_class.collection
+        expect{collection.insert(required_fields)}.to raise_exception(Moped::Errors::OperationFailure)
+      end
+    end
+  end
+end

data/spec/divisio/mongoid_adapter_spec.rb

@@ -0,0 +1,63 @@
+describe Divisio::MongoidAdapter do
+  let(:experiment) { 'experiment' }
+  let(:variants)   { [1, 2, 3] }
+  let(:identity)   { 'identity' }
+
+  describe '::split' do
+    subject{ described_class.split(experiment, variants, identity) }
+
+    it_behaves_like 'a base adapter'
+
+    context 'new record' do
+
+      it 'saves the experiment to the database' do
+        expect_any_instance_of(Divisio::MongoidAdapter::Experiment).to receive(:save)
+        subject
+      end
+
+      it 'converts the variant to string' do
+        expect(subject).to be_a String
+      end
+    end
+
+    context 'old record' do
+
+      before do
+        Divisio::MongoidAdapter::Experiment.create(name: experiment, identifier: identity, variant: 'random')
+      end
+
+      it 'returns the variant from mongo if already exists' do
+        expect(subject).to eq('random')
+      end
+
+      it 'does not re-save to the database' do
+        expect_any_instance_of(Divisio::MongoidAdapter::Experiment).to_not receive(:save)
+        subject
+      end
+    end
+  end
+
+  describe '::delete_experiment_for_identity' do
+    subject{ described_class.delete_experiment_for_identity(identity, experiment) }
+
+    context 'record exists in the database' do
+      before do
+        Divisio::MongoidAdapter::Experiment.create(name: experiment, identifier: identity, variant: 'random')
+      end
+
+      it 'deletes the record' do
+        expect{subject}.to change { Divisio::MongoidAdapter::Experiment.count }.from(1).to(0)
+      end
+
+      it 'returns true' do
+        expect(subject).to eq(true)
+      end
+    end
+
+    context 'record does not exist in the database' do
+      it 'returns false' do
+        expect(subject).to eq(false)
+      end
+    end
+  end
+end

data/spec/divisio/no_persistence_adapter_spec.rb

@@ -0,0 +1,4 @@
+describe Divisio::NoPersistenceAdapter do
+
+  it_behaves_like 'a base adapter'
+end

data/spec/divisio_spec.rb

@@ -0,0 +1,56 @@
+describe Divisio do
+  describe '::default_adapter' do
+    it 'has a default adapter' do
+      expect(Divisio.default_adapter).to eq(Divisio::NoPersistenceAdapter)
+    end
+  end
+
+  describe '::default_adapter=' do
+    before do
+      @default_adapter = Divisio.default_adapter
+    end
+
+    after do
+      Divisio.default_adapter = @default_adapter
+    end
+
+    it 'overwrites the default adapter' do
+      Divisio.default_adapter = Divisio::MongoidAdapter
+      expect(Divisio.default_adapter).to eq(Divisio::MongoidAdapter)
+    end
+  end
+
+  describe '::new' do
+    context 'no adapter provided to initializer' do
+      it 'initializes an object with a default adapter' do
+        framework = Divisio.new
+
+        expect(framework.instance_variable_get('@adapter')).to eq(Divisio.default_adapter)
+      end
+    end
+
+    context 'adapter provided to initializer' do
+      it 'initializes an object with a supplied adapter' do
+        framework = Divisio.new(adapter: Divisio::MongoidAdapter)
+
+        expect(framework.instance_variable_get('@adapter')).to eq(Divisio::MongoidAdapter)
+      end
+    end
+  end
+
+  describe '#split' do
+    it 'calls the same method on the adapter' do
+      expect(Divisio::MongoidAdapter).to receive(:split)
+
+      Divisio.new(adapter: Divisio::MongoidAdapter).split(anything, anything, anything)
+    end
+  end
+
+  describe '#delete_experiment_for_identity' do
+    it 'calls the same method on the adapter' do
+      expect(Divisio::MongoidAdapter).to receive(:delete_experiment_for_identity)
+
+      Divisio.new(adapter: Divisio::MongoidAdapter).delete_experiment_for_identity(anything, anything)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+ENV['RACK_ENV'] = 'test'
+
+Dir['./spec/support/**/*.rb'].sort.each { |f| require f}
+
+require 'mongoid'
+require 'divisio'
+
+Mongoid.load!('mongoid.yml')
+
+RSpec.configure do |config|
+  config.before(:each) do
+    Mongoid::Sessions.default.collections.each(&:drop)
+  end
+end

data/spec/support/shared_examples_for_base_adapter.rb

@@ -0,0 +1,17 @@
+shared_examples_for 'a base adapter' do
+
+  describe '::split' do
+    let(:experiment) { 'experiment' }
+    let(:variants)   { ['1', '2', '3'] }
+    let(:identity)   { 'identity' }
+    subject{ described_class.split(experiment, variants, identity) }
+
+    it 'returns a variant for the given experiment and identity' do
+      expect(subject).to eq('3')
+    end
+
+    it 'always assigns same variant for the same attributes' do
+      expect(described_class.split(experiment, variants, identity)).to eq(subject)
+    end
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: divisio
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dragos Miron
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-13 00:00:00.000000000 Z
+dependencies: []
+description: Provides a splitting framework similar to AB testing
+email:
+- tech@simplybusiness.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE.txt
+- README.md
+- divisio.gemspec
+- lib/divisio.rb
+- lib/divisio/base_adapter.rb
+- lib/divisio/modulo_algorithm.rb
+- lib/divisio/mongoid_adapter.rb
+- lib/divisio/mongoid_adapter/experiment.rb
+- lib/divisio/no_persistence_adapter.rb
+- lib/divisio/version.rb
+- mongoid.yml
+- spec/divisio/base_adapter_spec.rb
+- spec/divisio/modulo_algorithm_spec.rb
+- spec/divisio/mongoid_adapter/experiment_spec.rb
+- spec/divisio/mongoid_adapter_spec.rb
+- spec/divisio/no_persistence_adapter_spec.rb
+- spec/divisio_spec.rb
+- spec/spec_helper.rb
+- spec/support/shared_examples_for_base_adapter.rb
+homepage: http://www.simplybusiness.co.uk
+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.0.14
+signing_key: 
+specification_version: 4
+summary: Provides a splitting framework similar to AB testing
+test_files:
+- spec/divisio/base_adapter_spec.rb
+- spec/divisio/modulo_algorithm_spec.rb
+- spec/divisio/mongoid_adapter/experiment_spec.rb
+- spec/divisio/mongoid_adapter_spec.rb
+- spec/divisio/no_persistence_adapter_spec.rb
+- spec/divisio_spec.rb
+- spec/spec_helper.rb
+- spec/support/shared_examples_for_base_adapter.rb
+has_rdoc: