alephbet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5810939a6190541eae1871206aa006520f035e73db99691bbdb55774621ba46a
+  data.tar.gz: 5ccd87046ef852d8bab6916cc93ba6505f2a2a6ca0d97a5ebef14bcc505f8291
+SHA512:
+  metadata.gz: 22a3cdff22bb2e8879d3c405beb441dcd561a291f9abc01a7d08cd7949e25aacbaaa99e5b1a979345d7435194ed43b281bd0ed747e1c776c4c85aee5f485f266
+  data.tar.gz: c5d782af07facd9fb8505329d3f7f4a695f33149fb6f8701e05cda517a275d8937b248ba81dab39d26c920d93b92464e04fc6e1de64730b0aee34bd89699cb9e

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2020 
+
+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,99 @@
+# Alephbet
+A rails-engine backend for the [Alephbet](https://github.com/alephbet/alephbet) A/B testing framework.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'alephbet'
+```
+
+And then execute:
+```bash
+$ bundle
+$ bundle exec rails generate alephbet:install
+$ bundle exec rake db:migrate
+```
+
+Update your routes to mount alephbet:
+```ruby
+# config/routes.rb
+
+mount Alephbet::Engine => "/alephbet"
+```
+
+Add alephbet JS:
+```bash
+# with webpacker
+$ npm install --save alephbet
+```
+
+## Usage
+
+### running experiments
+
+Add javascript experiments:
+
+```javascript
+import AlephBet from "alephbet"
+
+// for more options, see https://github.com/alephbet/alephbet
+
+const adapter = new AlephBet.RailsAdapter(
+  "http://your.host/alephbet/event"  // URL of the mounted engine tracking action
+)
+
+const button_clicked = new AlephBet.Goal("button clicked")
+
+const experiment = new AlephBet.Experiment({
+  name: "my experiment",
+  tracking_adapter: adapter,
+  variants: {
+    "1-Blue": {
+      activate: () => { /* set button color to blue */ }
+    },
+    "2-Red": {
+      activate: () => { /* set button color to red */ }
+    }
+  }
+})
+
+experiment.add_goals([button_clicked])
+```
+
+### viewing results
+
+There's no built-in dashboard at the moment. However, the API is compatible with [Gimel](https://github.com/alephbet/gimel) and [Lamed](https://github.com/alephbet/lamed), the Alephbet backends running on AWS Lamba).
+
+To access your dashboard, run:
+```ruby
+bundle exec rake alephbet:dashboard
+```
+
+The url would include the API url and key (with default namespace), to access your experiment results
+
+### cleaning-up
+
+Alephbet stores unique ids for events in the database, as well as the tally of test results. Those take space and can
+also slow down response times. It's therefore advisable to clean-up old experiment data from time to time.
+
+For example:
+```ruby
+# delete all unique ids (use with care)
+> Alephbet::Tracking.delete_all
+
+# delete all unique ids older than 30 days
+> Alephbet::Tracking.where("created_at < ?", 30.days.ago).delete_all
+
+# delete all unique ids for experiment "buy button" in namespace "dev"
+> Alephbet::Tracking.where(:experiment => "buy button", :namespace => "dev").delete_all
+
+# delete experiment results for experiment "buy button" in namespace "dev"
+> Alephbet::Experiment.where(:experiment => "buy button", :namespace => "dev").delete_all
+```
+
+## Contributing
+Create an issue or submit a pull request.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Alephbet'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/assets/config/alephbet_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets/alephbet .css

data/app/assets/stylesheets/alephbet/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/alephbet/application_controller.rb

@@ -0,0 +1,5 @@
+module Alephbet
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+  end
+end

data/app/controllers/alephbet/management_controller.rb

@@ -0,0 +1,93 @@
+module Alephbet
+  class ManagementController < ApplicationController
+    PARAMS = %i[experiment variant event namespace].freeze
+
+    # acts a browser-friendly API endpoint
+    skip_before_action :verify_authenticity_token
+    before_action :cors_headers
+    before_action :check_api_key, :except => :cors_preflight_check
+
+    def experiments
+      namespace = permitted_params[:namespace] || "alephbet"
+      @scope = Alephbet::Experiment.where(:namespace => namespace)
+      refine_scope if permitted_params[:scope].present?
+
+      respond_to do |format|
+        format.json {
+          render :json => results, :status => :ok
+        }
+      end
+    end
+
+    def cors_preflight_check
+      head :ok
+    end
+
+    private
+
+    def results
+      unique_experiments.map { |experiment| experiment_data(experiment) }
+    end
+
+    def experiment_data(experiment)
+      {
+        :experiment => experiment,
+        :goals => unique_goals.map { |goal| goal_data(experiment, goal) }
+      }
+    end
+
+    def goal_data(experiment, goal)
+      {
+        :goal => goal,
+        :results => variants.map { |variant|
+          {
+            :label => variant,
+            :trials => counter_for(experiment, "participate", variant),
+            :successes => counter_for(experiment, goal, variant)
+          }
+        }
+      }
+    end
+
+    def counter_for(experiment, event, variant)
+      @scope.find { |item|
+        item.experiment == experiment &&
+        item.event == event &&
+        item.variant == variant
+      }.try(:counter).to_i
+    end
+
+    def unique_experiments
+      @scope.map(&:experiment).uniq
+    end
+
+    def variants
+      @scope.map(&:variant).uniq
+    end
+
+    def unique_goals
+      @scope.reject { |item| item.event == "participate" }.map(&:event).uniq
+    end
+
+    def check_api_key
+      api_header = request.headers["X-Api-Key"]
+      valid_key = ActiveSupport::SecurityUtils.secure_compare(Alephbet.api_key, api_header)
+      head :forbidden unless valid_key
+    end
+
+    def refine_scope
+      @scope = @scope.where(:experiment => permitted_params[:scope].split(","))
+    end
+
+    def permitted_params
+      params.permit(PARAMS)
+    end
+
+    def cors_headers
+      response.headers["Access-Control-Allow-Origin"] = Alephbet.cors_allow_origin
+      response.headers["Access-Control-Allow-Methods"] = "POST, GET, OPTIONS"
+      response.headers["Access-Control-Allow-Headers"] = Alephbet.cors_allow_headers
+      response.headers["Access-Control-Max-Age"] = "1728000"
+    end
+  end
+end

data/app/controllers/alephbet/tracking_controller.rb

@@ -0,0 +1,33 @@
+module Alephbet
+  class TrackingController < ApplicationController
+    PARAMS = %i[experiment variant event namespace uuid].freeze
+
+    def event
+      respond_to do |format|
+        format.json {
+          begin
+            Alephbet::Tracking.create(permitted_tracking_params)
+            Alephbet::Experiment.increment_counter(:counter, experiment_id)
+          rescue ActiveRecord::RecordNotUnique
+            # ignoring duplicate requests
+          end
+          render :json => {}, :status => :ok
+        }
+      end
+    end
+
+    private
+
+    def experiment_id
+      Alephbet::Experiment.find_or_create_by(permitted_experiment_params).id
+    end
+
+    def permitted_tracking_params
+      params.permit(PARAMS.without(:variant, :event))
+    end
+
+    def permitted_experiment_params
+      params.permit(PARAMS.without(:uuid))
+    end
+  end
+end

data/app/helpers/alephbet/application_helper.rb

@@ -0,0 +1,4 @@
+module Alephbet
+  module ApplicationHelper
+  end
+end

data/app/jobs/alephbet/application_job.rb

@@ -0,0 +1,4 @@
+module Alephbet
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/alephbet/application_mailer.rb

@@ -0,0 +1,6 @@
+module Alephbet
+  class ApplicationMailer < ActionMailer::Base
+    default from: 'from@example.com'
+    layout 'mailer'
+  end
+end

data/app/models/alephbet/application_record.rb

@@ -0,0 +1,5 @@
+module Alephbet
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/alephbet/experiment.rb

@@ -0,0 +1,22 @@
+# rubocop:disable Layout/LineLength
+# == Schema Information
+#
+# Table name: alephbet_experiments
+#
+#  id         :bigint           not null, primary key
+#  counter    :integer          default(0), not null
+#  event      :string           not null
+#  experiment :string           not null
+#  namespace  :string           default("alephbet"), not null
+#  variant    :string           not null
+#
+# Indexes
+#
+#  by_experiments  (namespace,experiment,variant,event) UNIQUE
+#
+# rubocop:enable Layout/LineLength
+
+module Alephbet
+  class Experiment < ApplicationRecord
+  end
+end

data/app/models/alephbet/tracking.rb

@@ -0,0 +1,22 @@
+# rubocop:disable Layout/LineLength
+# == Schema Information
+#
+# Table name: alephbet_tracking
+#
+#  id         :bigint           not null, primary key
+#  event      :string           not null
+#  experiment :string           not null
+#  namespace  :string           default("alephbet"), not null
+#  uuid       :string           not null
+#  variant    :string           not null
+#
+# Indexes
+#
+#  index_alephbet_tracking_on_uuid  (uuid) UNIQUE
+#
+# rubocop:enable Layout/LineLength
+module Alephbet
+  class Tracking < ApplicationRecord
+    self.table_name = "alephbet_tracking"
+  end
+end

data/app/views/layouts/alephbet/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Alephbet</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= stylesheet_link_tag    "alephbet/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,6 @@
+Alephbet::Engine.routes.draw do
+  get "experiments" => "management#experiments", :as => "alephbet_experiments"
+  match "experiments" => "management#cors_preflight_check", :via => :options
+
+  get "event" => "tracking#event"
+end

data/lib/alephbet.rb

@@ -0,0 +1,15 @@
+require "alephbet/engine"
+
+module Alephbet
+  class << self
+    attr_accessor :api_key, :cors_allow_origin, :cors_allow_headers
+
+    def setup
+      # fallback api_key if none specified
+      self.api_key = SecureRandom.uuid
+      self.cors_allow_origin = "*"
+      self.cors_allow_headers = "*"
+      yield(self) if block_given?
+    end
+  end
+end

data/lib/alephbet/engine.rb

@@ -0,0 +1,5 @@
+module Alephbet
+  class Engine < ::Rails::Engine
+    isolate_namespace Alephbet
+  end
+end

data/lib/alephbet/version.rb

@@ -0,0 +1,3 @@
+module Alephbet
+  VERSION = '0.1.0'
+end

data/lib/generators/alephbet/install_generator.rb

@@ -0,0 +1,40 @@
+require "rails/generators/active_record"
+
+module Alephbet
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+      desc "Generates (but does not run) a migration for the Alephbet tables"
+
+      source_paths << File.join(File.dirname(__FILE__), "templates")
+
+      def install
+        route "mount Alephbet::Engine => '/alephbet'"
+        template "initializer.rb", "config/initializers/alephbet.rb"
+      end
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def self.migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]" if requires_migration_number?
+      end
+
+      def self.requires_migration_number?
+        Rails::VERSION::MAJOR.to_i >= 5
+      end
+
+      def create_migration_file
+        options = {
+          :migration_version => migration_version
+        }
+        migration_template "migration.erb", "db/migrate/create_alephbet_tables.rb", options
+      end
+
+      def migration_version
+        self.class.migration_version
+      end
+    end
+  end
+end

data/lib/generators/alephbet/templates/initializer.rb

@@ -0,0 +1,5 @@
+Alephbet.setup do |config|
+  config.api_key = ENV["ALEPHBET_API_KEY"] || SecureRandom.uuid
+  config.cors_allow_origin = "*"
+  config.cors_allow_headers = "*"
+end

data/lib/generators/alephbet/templates/migration.erb

@@ -0,0 +1,22 @@
+class CreateAlephbetTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table "alephbet_tracking" do |t|
+      t.string :uuid, :null => false
+      t.string :experiment, :null => false
+      t.string :namespace, :null => false, :default => "alephbet"
+      t.timestamps
+    end
+
+    create_table "alephbet_experiments" do |t|
+      t.string :experiment, :null => false
+      t.string :variant, :null => false
+      t.string :event, :null => false
+      t.string :namespace, :null => false, :default => "alephbet"
+      t.integer :counter, :null => false, :default => 0
+      t.timestamps
+    end
+
+    add_index :alephbet_tracking, :uuid, :unique => true
+    add_index :alephbet_experiments, [:namespace, :experiment, :variant, :event], :unique => true, :name => "by_experiments"
+  end
+end

data/lib/tasks/alephbet_tasks.rake

@@ -0,0 +1,19 @@
+include Rails.application.routes.url_helpers
+
+namespace :alephbet do
+  desc "view experiment results"
+  task :dashboard => :environment do
+    base_url = root_url.chomp("/")
+    experiments_path = Alephbet::Engine.routes.url_helpers.alephbet_experiments_path
+    experiments_url = "#{base_url}#{experiments_path}"
+    puts "Open your browser and go to: " \
+         "https://codepen.io/anon/pen/LOGGZj/" \
+         "?experiment_url=#{experiments_url}&" \
+         "api_key=#{Alephbet.api_key}&" \
+         "namespace=alephbet"
+
+    return if base_url =~ /https/
+
+    puts "NOTE: #{experiments_url} without SSL. The dashboard works only with https"
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: alephbet
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yoav Aner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.2
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.2
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.2.2
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  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: https://github.com/alephbet/alephbet-rails
+email:
+- ''
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/alephbet_manifest.js
+- app/assets/stylesheets/alephbet/application.css
+- app/controllers/alephbet/application_controller.rb
+- app/controllers/alephbet/management_controller.rb
+- app/controllers/alephbet/tracking_controller.rb
+- app/helpers/alephbet/application_helper.rb
+- app/jobs/alephbet/application_job.rb
+- app/mailers/alephbet/application_mailer.rb
+- app/models/alephbet/application_record.rb
+- app/models/alephbet/experiment.rb
+- app/models/alephbet/tracking.rb
+- app/views/layouts/alephbet/application.html.erb
+- config/routes.rb
+- lib/alephbet.rb
+- lib/alephbet/engine.rb
+- lib/alephbet/version.rb
+- lib/generators/alephbet/install_generator.rb
+- lib/generators/alephbet/templates/initializer.rb
+- lib/generators/alephbet/templates/migration.erb
+- lib/tasks/alephbet_tasks.rake
+homepage: https://github.com/alephbet/alephbet-rails
+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: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Alephbet A/B testing backend for Rails
+test_files: []