gitlab-experiment 0.2.2 → 0.4.0

data/lib/gitlab/experiment/callbacks.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Gitlab
+  class Experiment
+    module Callbacks
+      extend ActiveSupport::Concern
+      include ActiveSupport::Callbacks
+
+      included do
+        define_callbacks(
+          :unsegmented_run,
+          skip_after_callbacks_if_terminated: true
+        )
+
+        define_callbacks(
+          :segmented_run,
+          skip_after_callbacks_if_terminated: false,
+          terminator: lambda do |target, result_lambda|
+            result_lambda.call
+            target.variant_assigned?
+          end
+        )
+      end
+
+      class_methods do
+        def segment(*filter_list, variant:, **options, &block)
+          filters = filter_list.unshift(block).compact.map do |filter|
+            result_lambda = ActiveSupport::Callbacks::CallTemplate.build(filter, self).make_lambda
+            ->(target) { target.variant(variant) if result_lambda.call(target, nil) }
+          end
+
+          raise ArgumentError, 'no filters provided' if filters.empty?
+
+          set_callback(:segmented_run, :before, *filters, options, &block)
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/experiment/configuration.rb

@@ -13,7 +13,13 @@ module Gitlab
       @name_prefix = nil
 
       # The logger is used to log various details of the experiments.
-      @logger = Logger.new(STDOUT)
+      @logger = Logger.new($stdout)
+
+      # The base class that should be instantiated for basic experiments.
+      @base_class = 'Gitlab::Experiment'
+
+      # Cache layer. Expected to respond to fetch, like Rails.cache.
+      @cache = nil
 
       # Logic this project uses to resolve a variant for a given experiment.
       @variant_resolver = lambda do |requested_variant|
@@ -21,25 +27,39 @@ module Gitlab
       end
 
       # Tracking behavior can be implemented to link an event to an experiment.
-      @tracking_behavior = lambda do |action, event_args|
-        Configuration.logger.info "Gitlab::Experiment[#{name}] #{action}: #{event_args.merge(signature: signature)}"
+      @tracking_behavior = lambda do |event, args|
+        Configuration.logger.info "Gitlab::Experiment[#{name}] #{event}: #{args.merge(signature: signature)}"
       end
 
       # Called at the end of every experiment run, with the results. You may
       # want to push the experiment into the client or push results elsewhere.
       @publishing_behavior = lambda do |_result|
-        track(:assignment) # this will call the config.tracking_behavior
+        track(:assignment)
       end
 
       # Algorithm that consistently generates a hash key for a given hash map.
-      @context_hash_strategy = lambda do |context|
-        values = context.values.map { |v| (v.respond_to?(:to_global_id) ? v.to_global_id : v).to_s }
-        Digest::MD5.hexdigest((context.keys + values).join('|'))
+      @context_hash_strategy = lambda do |hash_map|
+        values = hash_map.values.map { |v| (v.respond_to?(:to_global_id) ? v.to_global_id : v).to_s }
+        Digest::MD5.hexdigest(([name] + hash_map.keys + values).join('|'))
       end
 
+      # The domain for which this cookie applies so you can restrict to the domain level.
+      # When not set, it uses the current host. If you want to provide specific hosts, you can
+      # provide them either via an array like `['www.gitlab.com', .gitlab.com']`, or set it to `:all`.
+      @cookie_domain = :all
+
       class << self
-        attr_accessor :name_prefix, :logger
-        attr_accessor :variant_resolver, :tracking_behavior, :publishing_behavior, :context_hash_strategy
+        attr_accessor(
+          :name_prefix,
+          :logger,
+          :base_class,
+          :cache,
+          :variant_resolver,
+          :tracking_behavior,
+          :publishing_behavior,
+          :context_hash_strategy,
+          :cookie_domain
+        )
       end
     end
   end

data/lib/gitlab/experiment/context.rb

@@ -3,82 +3,65 @@
 module Gitlab
   class Experiment
     class Context
+      include Cookies
+
       DNT_REGEXP = /^(true|t|yes|y|1|on)$/i.freeze
 
-      def initialize(experiment)
+      def initialize(experiment, **initial_value)
         @experiment = experiment
         @value = {}
-        @migrations_from = []
-        @migrations_with = []
+        @migrations = { merged: [], unmerged: [] }
+
+        value(initial_value)
+      end
+
+      def reinitialize(request)
+        @signature = nil # clear memoization
+        @request = request if request.respond_to?(:headers) && request.respond_to?(:cookie_jar)
       end
 
       def value(value = nil)
         return @value if value.nil?
 
         value = value.dup # dup so we don't mutate
-        @signature = nil # clear memoized signature
+        reinitialize(value.delete(:request))
 
-        @migrations_from << value.delete(:migrated_from) if value[:migrated_from]
-        @migrations_with << value.delete(:migrated_with) if value[:migrated_with]
-        @value.merge!(migrate_cookie_to_user_id(value))
+        @value.merge!(process_migrations(value))
+      end
+
+      def trackable?
+        !(@request && @request.headers['DNT'].to_s.match?(DNT_REGEXP))
       end
 
       def freeze
-        signature # ensure we're done before being frozen
+        signature # finalize before freezing
         super
       end
 
       def signature
-        @signature ||= {
-          key: key_for(@value),
-          migration_keys: migration_keys,
-          variant: @experiment.variant.name
-        }.compact
+        @signature ||= { key: @experiment.key_for(@value), migration_keys: migration_keys }.compact
       end
 
       private
 
-      def migrate_cookie_to_user_id(hash)
-        return hash unless (request = hash.delete(:request))
-        return hash unless request.respond_to?(:headers) && request.respond_to?(:cookie_jar)
-        return hash if request.headers['DNT'].to_s.match?(DNT_REGEXP)
-
-        jar = request.cookie_jar
-        resolver = [jar, hash, :user_id, jar.signed[cookie_name]].compact
-        resolve_cookie(*resolver) or generate_cookie(*resolver)
-      end
+      def process_migrations(value)
+        add_migration(value.delete(:migrated_from))
+        add_migration(value.delete(:migrated_with), merge: true)
 
-      def cookie_name
-        @cookie_name ||= [@experiment.name, 'id'].join('_')
+        migrate_cookie(value, "#{@experiment.name}_id")
       end
 
-      def resolve_cookie(jar, hash, key, cookie = nil)
-        return if cookie.blank? && hash[key].blank?
-        return hash.merge(key => cookie) if hash[key].blank?
-
-        @migrations_with << { user_id: cookie }
-        jar.delete(cookie_name, domain: :all)
+      def add_migration(value, merge: false)
+        return unless value.is_a?(Hash)
 
-        hash
-      end
-
-      def generate_cookie(jar, hash, key, cookie = SecureRandom.uuid)
-        jar.permanent.signed[cookie_name] = {
-          value: cookie, secure: true, domain: :all, httponly: true
-        }
-
-        hash.merge(key => cookie)
+        @migrations[merge ? :merged : :unmerged] << value
       end
 
       def migration_keys
-        return nil if @migrations_from.empty? && @migrations_with.empty?
-
-        @migrations_from.map { |m| key_for(m) } +
-          @migrations_with.map { |m| key_for(@value.merge(m)) }
-      end
+        return nil if @migrations[:unmerged].empty? && @migrations[:merged].empty?
 
-      def key_for(context)
-        Configuration.context_hash_strategy.call(context)
+        @migrations[:unmerged].map { |m| @experiment.key_for(m) } +
+          @migrations[:merged].map { |m| @experiment.key_for(@value.merge(m)) }
       end
     end
   end

data/lib/gitlab/experiment/cookies.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Gitlab
+  class Experiment
+    module Cookies
+      private
+
+      def migrate_cookie(hash, cookie_name)
+        return hash if cookie_jar.nil?
+
+        resolver = [hash, :actor, cookie_name, cookie_jar.signed[cookie_name]]
+        resolve_cookie(*resolver) or generate_cookie(*resolver)
+      end
+
+      def cookie_jar
+        @request&.cookie_jar
+      end
+
+      def resolve_cookie(hash, key, cookie_name, cookie)
+        return if cookie.to_s.empty? && hash[key].nil?
+        return hash if cookie.to_s.empty?
+        return hash.merge(key => cookie) if hash[key].nil?
+
+        add_migration(key => cookie)
+        cookie_jar.delete(cookie_name, domain: domain)
+
+        hash
+      end
+
+      def generate_cookie(hash, key, cookie_name, cookie)
+        return hash unless hash.key?(key)
+
+        cookie ||= SecureRandom.uuid
+        cookie_jar.permanent.signed[cookie_name] = {
+          value: cookie, secure: true, domain: domain, httponly: true
+        }
+
+        hash.merge(key => cookie)
+      end
+
+      def domain
+        Configuration.cookie_domain
+      end
+    end
+  end
+end

data/lib/gitlab/experiment/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   class Experiment
-    VERSION = '0.2.2'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,35 +1,49 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - GitLab
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-09-24 00:00:00.000000000 Z
+date: 2020-11-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: scientist
+  name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.5.0
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: scientist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.0
 description: 
 email:
 - gitlab_rubygems@gitlab.com
@@ -39,12 +53,23 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
-- lib/generators/gitlab_experiment/install/POST_INSTALL
-- lib/generators/gitlab_experiment/install/install_generator.rb
-- lib/generators/gitlab_experiment/install/templates/initializer.rb
+- lib/generators/gitlab/experiment/USAGE
+- lib/generators/gitlab/experiment/experiment_generator.rb
+- lib/generators/gitlab/experiment/install/install_generator.rb
+- lib/generators/gitlab/experiment/install/templates/POST_INSTALL
+- lib/generators/gitlab/experiment/install/templates/application_experiment.rb.tt
+- lib/generators/gitlab/experiment/install/templates/initializer.rb.tt
+- lib/generators/gitlab/experiment/templates/experiment.rb.tt
+- lib/generators/rspec/experiment/experiment_generator.rb
+- lib/generators/rspec/experiment/templates/experiment_spec.rb.tt
+- lib/generators/test_unit/experiment/experiment_generator.rb
+- lib/generators/test_unit/experiment/templates/experiment_test.rb.tt
 - lib/gitlab/experiment.rb
+- lib/gitlab/experiment/caching.rb
+- lib/gitlab/experiment/callbacks.rb
 - lib/gitlab/experiment/configuration.rb
 - lib/gitlab/experiment/context.rb
+- lib/gitlab/experiment/cookies.rb
 - lib/gitlab/experiment/dsl.rb
 - lib/gitlab/experiment/engine.rb
 - lib/gitlab/experiment/variant.rb
@@ -68,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: GitLab experiment library built on top of scientist.

data/lib/generators/gitlab_experiment/install/install_generator.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-require 'rails/generators'
-
-module GitlabExperiment
-  module Generators
-    class InstallGenerator < Rails::Generators::Base
-      source_root File.expand_path(__dir__)
-
-      desc 'Installs the Gitlab Experiment initializer into your application.'
-
-      def copy_initializers
-        copy_file 'templates/initializer.rb', 'config/initializers/gitlab_experiment.rb'
-      end
-
-      def display_post_install
-        readme 'POST_INSTALL' if behavior == :invoke
-      end
-    end
-  end
-end

data/lib/generators/gitlab_experiment/install/templates/initializer.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-Gitlab::Experiment.configure do |config|
-  # Prefix all experiment names with a given value. Use `nil` for none.
-  config.name_prefix = nil
-
-  # The logger is used to log various details of the experiments.
-  config.logger = Logger.new(STDOUT)
-
-  # Logic this project uses to resolve a variant for a given experiment.
-  #
-  # This can return an instance of any object that responds to `name`, or can
-  # return a variant name as a string, in which case the build in variant
-  # class will be used.
-  #
-  # This block will be executed within the scope of the experiment instance,
-  # so can easily access experiment methods, like getting the name or context.
-  config.variant_resolver = lambda do |requested_variant|
-    # An example of running the control, unless a variant was requested:
-    requested_variant || 'control'
-
-    # Always run candidate, unless a variant was requested, with fallback:
-    # variant_name || variant_names.first || 'control'
-
-    # Using unleash to determine the variant:
-    # TODO: this isn't entirely accurate.
-    # fallback = Unleash::Variant.new(name: requested_variant || 'control', enabled: true)
-    # UNLEASH.get_variant(name, context.value, fallback)
-
-    # Using Flipper to determine the variant:
-    # TODO: provide example.
-    # Variant.new(name: resolved)
-  end
-
-  # Tracking behavior can be implemented to link an event to an experiment.
-  #
-  # Similar to the variant resolver, this is called within the scope of the
-  # experiment instance and so can access any methods on the experiment.
-  config.tracking_behavior = lambda do |action, event_args|
-    # An example of using a generic logger to track events:
-    (event_args[:context] ||= []) << context.signature.merge(group: variant.name)
-    config.logger.info "Gitlab::Experiment[#{name}] #{action}: #{event_args}"
-
-    # Using something like snowplow to track events:
-    # (event_args[:context] ||= []) << SnowplowTracker::SelfDescribingJson.new(
-    #   'iglu:com.gitlab/gitlab_experiment/jsonschema/1-0-0',
-    #   experiment: context.signature.merge(group: variant.name)
-    # )
-    #
-    # Tracking.event(name, action, **event_args)
-  end
-
-  # Called at the end of every experiment run, with the result.
-  #
-  # You may want to track that you've assigned a variant to a given context,
-  # or push the experiment into the client or publish results elsewhere, like
-  # into redis.
-  config.publishing_behavior = lambda do |_result|
-    track(:assignment) # this will call the config.tracking_behavior
-
-    # Log the results, so we can inspect them if we wanted to later.
-    # LogRage.log(result: _result)
-
-    # Push the experiment knowledge into the client using Gon.
-    # Gon.push(experiment: { name => signature })
-  end
-
-  # Algorithm that consistently generates a hash key for a given hash map.
-  #
-  # Given a specific context hash map, we need to generate a consistent hash
-  # key. The logic in here will be used for generating cache keys, and may also
-  # be used when determining which variant may be presented.
-  config.context_hash_strategy = lambda do |context|
-    values = context.values.map { |v| (v.respond_to?(:to_global_id) ? v.to_global_id : v).to_s }
-    Digest::MD5.hexdigest((context.keys + values).join('|'))
-  end
-end