gitlab-experiment 0.5.4 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d7bc7a1946d06b5188ccfe761342209779f75cf635d894bb8743519ff2830dc
-  data.tar.gz: 7a5c347f8b58e5caa2fe814ce013dbf1ca71f6e017148528a0ff2ca74bd562de
+  metadata.gz: ed3c0028563936ce8a3fbdfd1de9d64e499102c4ec71a21946b63c56cc2bebd5
+  data.tar.gz: 43389ef9b7b2a4b3e60b82b5ffefbe3635739cb9fafec21dd5e9d59586f942c2
 SHA512:
-  metadata.gz: '01927d9db97ad4b087d445db642aa39615faa68322e2bd0e0b82ae99441478bae3f1939b94956218121fe52d01f432836ba272d0b1ff052537c80f0d0ff107b3'
-  data.tar.gz: f53702ea5bb97fe6c73427850534b9e156744336a37029dce2b96926b70b7a5c4959708ac626f6ac0435125ad4ffe62f2ba9fd528f756af811c6ff66abc47846
+  metadata.gz: 30d0988d199f34eb60e3d56d8e7aec3a00222a5de482410c0294e15ce37a2a9dccbb2fb35b372c90b4425879938bec0d7e5b0ffadf5d842ee31abb0ea673aaeb
+  data.tar.gz: 3665443e1d937b77e12debaf3195423b3fad171b651573e58a328dfb5c1f618eb9a282eedcfde68376ae0e7207837b74ae60e4fda616c046caa329b4cc681e68

data/README.md

@@ -423,6 +423,30 @@ Gitlab::Experiment.configure do |config|
 end
 ```
 
+### Middleware
+
+There are times when you'll need to do link tracking in email templates, or markdown content -- or other places you won't be able to implement tracking. For these cases, gitlab-experiment comes with middleware that will redirect to a given URL while also tracking that the URL was visited.
+
+In Rails this middleware is mounted automatically, with a base path of what's been configured for `mount_at`. If this path is empty the middleware won't be mounted at all.
+
+Once mounted, the redirect URLs can be generated using the Rails route helpers. If not using Rails, mount the middleware and generate these URLs yourself.
+
+```ruby
+Gitlab::Experiment.configure do |config|
+  config.mount_at = '/experiment'
+end
+
+ex = experiment(:example, foo: :bar)
+
+# using rails path/url helpers 
+experiment_redirect_path(ex, 'https//docs.gitlab.com/') # => /experiment/example:[context_key]?https//docs.gitlab.com/
+
+# manually
+"#{Gitlab::Experiment.configure.mount_at}/#{ex.to_param}?https//docs.gitlab.com/"
+```
+
+URLS that match the base path will be handled by the middleware and will redirect to the provided redirect path.
+
 ## Testing (rspec support)
 
 This gem comes with some rspec helpers and custom matchers. These are in flux at the time of writing.

data/lib/generators/gitlab/experiment/install/templates/initializer.rb.tt

@@ -18,8 +18,10 @@ Gitlab::Experiment.configure do |config|
   # The domain to use on cookies.
   #
   # When not set, it uses the current host. If you want to provide specific
-  # hosts, you use `:all`, or provide an array like
-  # `['www.gitlab.com', '.gitlab.com']`.
+  # hosts, you use `:all`, or provide an array.
+  #
+  # Examples:
+  #   nil, :all, or ['www.gitlab.com', '.gitlab.com']
   config.cookie_domain = :all
 
   # The default rollout strategy that works for single and multi-variants.
@@ -28,8 +30,41 @@ Gitlab::Experiment.configure do |config|
   # experiment.
   #
   # Examples include:
-  #   Rollout::First, Rollout::Random, Rollout::RoundRobin
-  config.default_rollout = Gitlab::Experiment::Rollout::First
+  #   Rollout::Random, or Rollout::RoundRobin
+  config.default_rollout = Gitlab::Experiment::Rollout::Percent
+
+  # Secret seed used in generating context keys.
+  #
+  # Consider not using one that's shared with other systems, like Rails'
+  # SECRET_KEY_BASE. Generate a new secret and utilize that instead.
+  @context_key_secret = nil
+
+  # Bit length used by SHA2 in generating context keys.
+  #
+  # Using a higher bit length would require more computation time.
+  #
+  # Valid bit lengths:
+  #   256, 384, or 512.
+  @context_key_bit_length = 256
+
+  # The default base path that the middleware (or rails engine) will be
+  # mounted. Can be nil if you don't want anything to be mounted automatically.
+  #
+  # This enables a similar behavior to how links are instrumented in emails.
+  #
+  # Examples:
+  #   '/-/experiment', '/redirect', nil
+  config.mount_at = '/experiment'
+
+  # When using the middleware, links can be instrumented and redirected
+  # elsewhere. This can be exploited to make a harmful url look innocuous or
+  # that it's a valid url on your domain. To avoid this, you can provide your
+  # own logic for what urls will be considered valid and redirected to.
+  #
+  # Expected to return a boolean value.
+  config.redirect_url_validator = lambda do |redirect_url|
+    true
+  end
 
   # Logic this project uses to determine inclusion in a given experiment.
   #
@@ -80,17 +115,4 @@ Gitlab::Experiment.configure do |config|
     #
     # Lograge::Event.log(experiment: name, result: result, signature: 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.
-  #
-  # This block is executed within the scope of the experiment and so can access
-  # experiment methods, like `name`, `context`, and `signature`.
-  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

data/lib/gitlab/experiment.rb

@@ -9,6 +9,7 @@ require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/string/inflections'
 require 'active_support/core_ext/module/delegation'
 
+require 'gitlab/experiment/errors'
 require 'gitlab/experiment/base_interface'
 require 'gitlab/experiment/cache'
 require 'gitlab/experiment/callbacks'
@@ -17,6 +18,7 @@ require 'gitlab/experiment/configuration'
 require 'gitlab/experiment/cookies'
 require 'gitlab/experiment/context'
 require 'gitlab/experiment/dsl'
+require 'gitlab/experiment/middleware'
 require 'gitlab/experiment/variant'
 require 'gitlab/experiment/version'
 require 'gitlab/experiment/engine' if defined?(Rails::Engine)
@@ -102,6 +104,8 @@ module Gitlab
 
     def run(variant_name = nil)
       @result ||= super(variant(variant_name).name)
+    rescue Scientist::BehaviorMissing => e
+      raise Error, e
     end
 
     def publish(result)
@@ -116,6 +120,13 @@ module Gitlab
       instance_exec(action, event_args, &Configuration.tracking_behavior)
     end
 
+    def process_redirect_url(url)
+      return unless Configuration.redirect_url_validator&.call(url)
+
+      track('visited', url: url)
+      url # return the url, which allows for mutation
+    end
+
     def enabled?
       true
     end
@@ -139,11 +150,25 @@ module Gitlab
     end
 
     def key_for(source, seed = name)
-      instance_exec(source, seed, &Configuration.context_hash_strategy)
+      # TODO: Added deprecation in release 0.6.0
+      if (block = Configuration.instance_variable_get(:@__context_hash_strategy))
+        return instance_exec(source, seed, &block)
+      end
+
+      source = source.keys + source.values if source.is_a?(Hash)
+
+      ingredients = Array(source).map { |v| identify(v) }
+      ingredients.unshift(seed).unshift(Configuration.context_key_secret)
+
+      Digest::SHA2.new(Configuration.context_key_bit_length).hexdigest(ingredients.join('|'))
     end
 
     protected
 
+    def identify(object)
+      (object.respond_to?(:to_global_id) ? object.to_global_id : object).to_s
+    end
+
     def segmentation_callback_chain
       return :segmentation_check if @variant_name.nil? && enabled? && !excluded?
 

data/lib/gitlab/experiment/base_interface.rb

@@ -26,6 +26,12 @@ module Gitlab
 
           experiment_name(name).classify.safe_constantize || Configuration.base_class.constantize
         end
+
+        def from_param(id)
+          %r{/?(?<name>.*):(?<key>.*)$} =~ id
+          name = CGI.unescape(name) if name
+          constantize(name).new(name).tap { |e| e.context.key(key) }
+        end
       end
 
       def initialize(name = nil, variant_name = nil, **context)
@@ -45,9 +51,10 @@ module Gitlab
       end
 
       def id
-        "#{name}:#{key_for(context.value)}"
+        "#{name}:#{context.key}"
       end
       alias_method :session_id, :id
+      alias_method :to_param, :id
 
       def flipper_id
         "Experiment;#{id}"

data/lib/gitlab/experiment/configuration.rb

@@ -31,15 +31,27 @@ module Gitlab
       # experiments.
       @default_rollout = Rollout::Base.new
 
+      # Secret seed used in generating context keys.
+      @context_key_secret = nil
+
+      # Bit length used by SHA2 in generating context keys - (256, 384 or 512.)
+      @context_key_bit_length = 256
+
+      # The default base path that the middleware (or rails engine) will be
+      # mounted.
+      @mount_at = nil
+
+      # The middleware won't redirect to urls that aren't considered valid.
+      # Expected to return a boolean value.
+      @redirect_url_validator = ->(_redirect_url) { true }
+
       # Logic this project uses to determine inclusion in a given experiment.
       # Expected to return a boolean value.
-      @inclusion_resolver = lambda do |requested_variant|
-        false
-      end
+      @inclusion_resolver = ->(_requested_variant) { false }
 
       # Tracking behavior can be implemented to link an event to an experiment.
       @tracking_behavior = lambda do |event, args|
-        Configuration.logger.info "Gitlab::Experiment[#{name}] #{event}: #{args.merge(signature: signature)}"
+        Configuration.logger.info("#{self.class.name}[#{name}] #{event}: #{args.merge(signature: signature)}")
       end
 
       # Called at the end of every experiment run, with the result.
@@ -47,24 +59,24 @@ module Gitlab
         track(:assignment)
       end
 
-      # Algorithm that consistently generates a hash key for a given source.
-      @context_hash_strategy = lambda do |source, seed|
-        source = source.keys + source.values if source.is_a?(Hash)
-        data = Array(source).map { |v| (v.respond_to?(:to_global_id) ? v.to_global_id : v).to_s }
-        Digest::MD5.hexdigest(data.unshift(seed).join('|'))
-      end
-
       class << self
+        # TODO: Added deprecation in release 0.6.0
+        def context_hash_strategy=(block)
+          ActiveSupport::Deprecation.warn('context_hash_strategy has been deprecated, instead configure' \
+            ' `context_key_secret` and `context_key_bit_length`.')
+          @__context_hash_strategy = block
+        end
+
         # TODO: Added deprecation in release 0.5.0
         def variant_resolver
           ActiveSupport::Deprecation.warn('variant_resolver is deprecated, instead use `inclusion_resolver` with a' \
-            'block that returns a boolean.')
+            ' block that returns a boolean.')
           @inclusion_resolver
         end
 
         def variant_resolver=(block)
           ActiveSupport::Deprecation.warn('variant_resolver is deprecated, instead use `inclusion_resolver` with a' \
-            'block that returns a boolean.')
+            ' block that returns a boolean.')
           @inclusion_resolver = block
         end
 
@@ -74,11 +86,14 @@ module Gitlab
           :base_class,
           :cache,
           :cookie_domain,
+          :context_key_secret,
+          :context_key_bit_length,
+          :mount_at,
           :default_rollout,
+          :redirect_url_validator,
           :inclusion_resolver,
           :tracking_behavior,
-          :publishing_behavior,
-          :context_hash_strategy
+          :publishing_behavior
         )
       end
     end

data/lib/gitlab/experiment/context.rb

@@ -31,6 +31,12 @@ module Gitlab
         @value.merge!(process_migrations(value))
       end
 
+      def key(key = nil)
+        return @key || @experiment.key_for(value) if key.nil?
+
+        @key = key
+      end
+
       def trackable?
         !(@request && @request.headers['DNT'].to_s.match?(DNT_REGEXP))
       end
@@ -41,7 +47,7 @@ module Gitlab
       end
 
       def signature
-        @signature ||= { key: @experiment.key_for(@value), migration_keys: migration_keys }.compact
+        @signature ||= { key: key, migration_keys: migration_keys }.compact
       end
 
       def method_missing(method_name, *)
@@ -55,16 +61,18 @@ module Gitlab
       private
 
       def process_migrations(value)
-        add_migration(value.delete(:migrated_from))
-        add_migration(value.delete(:migrated_with), merge: true)
+        add_unmerged_migration(value.delete(:migrated_from))
+        add_merged_migration(value.delete(:migrated_with))
 
         migrate_cookie(value, "#{@experiment.name}_id")
       end
 
-      def add_migration(value, merge: false)
-        return unless value.is_a?(Hash)
+      def add_unmerged_migration(value = {})
+        @migrations[:unmerged] << value if value.is_a?(Hash)
+      end
 
-        @migrations[merge ? :merged : :unmerged] << value
+      def add_merged_migration(value = {})
+        @migrations[:merged] << value if value.is_a?(Hash)
       end
 
       def migration_keys

data/lib/gitlab/experiment/cookies.rb

@@ -23,7 +23,7 @@ module Gitlab
         return hash if cookie.to_s.empty?
         return hash.merge(key => cookie) if hash[key].nil?
 
-        add_migration(key => cookie)
+        add_unmerged_migration(key => cookie)
         cookie_jar.delete(cookie_name, domain: domain)
 
         hash

data/lib/gitlab/experiment/dsl.rb

@@ -3,6 +3,10 @@
 module Gitlab
   class Experiment
     module Dsl
+      def self.include_in(klass, with_helper: false)
+        klass.include(self).tap { |base| base.helper_method(:experiment) if with_helper }
+      end
+
       def experiment(name, variant_name = nil, **context, &block)
         raise ArgumentError, 'name is required' if name.nil?
 

data/lib/gitlab/experiment/engine.rb

@@ -1,21 +1,46 @@
 # frozen_string_literal: true
 
+require 'active_model'
+
 module Gitlab
   class Experiment
+    include ActiveModel::Model
+
+    # used for generating routes
+    def self.model_name
+      ActiveModel::Name.new(self, Gitlab)
+    end
+
     class Engine < ::Rails::Engine
-      def self.include_dsl
-        if defined?(ActionController)
-          ActionController::Base.include(Dsl)
-          ActionController::Base.helper_method(:experiment)
-        end
+      isolate_namespace Experiment
+
+      initializer('gitlab_experiment.include_dsl') { include_dsl }
+      initializer('gitlab_experiment.mount_engine') { |app| mount_engine(app, Configuration.mount_at) }
 
-        return unless defined?(ActionMailer)
+      private
 
-        ActionMailer::Base.include(Dsl)
-        ActionMailer::Base.helper_method(:experiment)
+      def include_dsl
+        Dsl.include_in(ActionController::Base, with_helper: true) if defined?(ActionController)
+        Dsl.include_in(ActionMailer::Base, with_helper: true) if defined?(ActionMailer)
       end
 
-      config.after_initialize { include_dsl }
+      def mount_engine(app, mount_at)
+        return if mount_at.blank?
+
+        engine = routes do
+          default_url_options app.routes.default_url_options.clone.without(:script_name)
+          resources :experiments, path: '/', only: :show
+        end
+
+        app.config.middleware.use(Middleware, mount_at)
+        app.routes.append do
+          mount Engine, at: mount_at, as: :experiment_engine
+          direct(:experiment_redirect) do |ex, options|
+            url = options[:url]
+            "#{engine.url_helpers.experiment_url(ex)}?#{url}"
+          end
+        end
+      end
     end
   end
 end

data/lib/gitlab/experiment/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Gitlab
+  class Experiment
+    Error = Class.new(StandardError)
+    InvalidRolloutRules = Class.new(Error)
+  end
+end

data/lib/gitlab/experiment/middleware.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Gitlab
+  class Experiment
+    class Middleware
+      def self.redirect(id, url)
+        raise Error, 'no url to redirect to' if url.blank?
+
+        experiment = Gitlab::Experiment.from_param(id)
+        [303, { 'Location' => experiment.process_redirect_url(url) || raise(Error, 'not redirecting') }, []]
+      end
+
+      def initialize(app, base_path)
+        @app = app
+        @matcher = %r{^#{base_path}/(?<id>.+)}
+      end
+
+      def call(env)
+        return @app.call(env) if env['REQUEST_METHOD'] != 'GET' || (match = @matcher.match(env['PATH_INFO'])).nil?
+
+        Middleware.redirect(match[:id], env['QUERY_STRING'])
+      rescue Error
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/gitlab/experiment/rollout.rb

@@ -3,6 +3,7 @@
 module Gitlab
   class Experiment
     module Rollout
+      autoload :Percent, 'gitlab/experiment/rollout/percent.rb'
       autoload :Random, 'gitlab/experiment/rollout/random.rb'
       autoload :RoundRobin, 'gitlab/experiment/rollout/round_robin.rb'
 
@@ -15,17 +16,23 @@ module Gitlab
       class Base
         attr_reader :experiment
 
-        delegate :variant_names, :cache, to: :experiment
+        delegate :variant_names, :cache, :id, to: :experiment
 
         def initialize(options = {})
           @options = options
+          # validate! # we want to validate here, but we can't yet
         end
 
         def rollout_for(experiment)
           @experiment = experiment
+          validate! # until we have variant registration we can only validate here
           execute
         end
 
+        def validate!
+          # base is always valid
+        end
+
         def execute
           variant_names.first
         end

data/lib/gitlab/experiment/rollout/percent.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+module Gitlab
+  class Experiment
+    module Rollout
+      class Percent < Base
+        def execute
+          crc = normalized_id
+          total = 0
+
+          case distribution_rules
+          # run through the rules until finding an acceptable one
+          when Array then variant_names[distribution_rules.find_index { |percent| crc % 100 <= total += percent }]
+          # run through the variant names until finding an acceptable one
+          when Hash then distribution_rules.find { |_, percent| crc % 100 <= total += percent }.first
+          # when there are no rules, assume even distribution
+          else variant_names[crc % variant_names.length]
+          end
+        end
+
+        def validate!
+          case distribution_rules
+          when nil then nil
+          when Array, Hash
+            if distribution_rules.length != variant_names.length
+              raise InvalidRolloutRules, "the distribution rules don't match the number of variants defined"
+            end
+          else
+            raise InvalidRolloutRules, 'unknown distribution options type'
+          end
+        end
+
+        private
+
+        def normalized_id
+          Zlib.crc32(id, nil)
+        end
+
+        def distribution_rules
+          @options[:distribution]
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/experiment/rspec.rb

@@ -82,7 +82,7 @@ module Gitlab
       extend RSpec::Matchers::DSL
 
       def require_experiment(experiment, matcher_name, classes: false)
-        klass = experiment.class == Class ? experiment : experiment.class
+        klass = experiment.instance_of?(Class) ? experiment : experiment.class
         unless klass <= Gitlab::Experiment
           raise(
             ArgumentError,

data/lib/gitlab/experiment/variant.rb

@@ -2,6 +2,10 @@
 
 module Gitlab
   class Experiment
-    Variant = Struct.new(:name, :payload, keyword_init: true)
+    Variant = Struct.new(:name, :payload, keyword_init: true) do
+      def group
+        name == 'control' ? :control : :experiment
+      end
+    end
   end
 end

data/lib/gitlab/experiment/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   class Experiment
-    VERSION = '0.5.4'
+    VERSION = '0.6.4'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.6.4
 platform: ruby
 authors:
 - GitLab
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-05-05 00:00:00.000000000 Z
+date: 
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -65,35 +65,52 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE.txt
-- README.md
-- lib/generators/gitlab/experiment/USAGE
-- lib/generators/gitlab/experiment/experiment_generator.rb
+- lib/generators/gitlab
+- lib/generators/gitlab/experiment
+- lib/generators/gitlab/experiment/install
 - lib/generators/gitlab/experiment/install/install_generator.rb
-- lib/generators/gitlab/experiment/install/templates/POST_INSTALL
+- lib/generators/gitlab/experiment/install/templates
 - lib/generators/gitlab/experiment/install/templates/application_experiment.rb.tt
 - lib/generators/gitlab/experiment/install/templates/initializer.rb.tt
+- lib/generators/gitlab/experiment/install/templates/POST_INSTALL
+- lib/generators/gitlab/experiment/USAGE
+- lib/generators/gitlab/experiment/experiment_generator.rb
+- lib/generators/gitlab/experiment/templates
 - 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
+- lib/generators/test_unit/experiment
 - lib/generators/test_unit/experiment/experiment_generator.rb
+- lib/generators/test_unit/experiment/templates
 - lib/generators/test_unit/experiment/templates/experiment_test.rb.tt
+- lib/generators/rspec
+- lib/generators/rspec/experiment
+- lib/generators/rspec/experiment/experiment_generator.rb
+- lib/generators/rspec/experiment/templates
+- lib/generators/rspec/experiment/templates/experiment_spec.rb.tt
 - lib/gitlab/experiment.rb
-- lib/gitlab/experiment/base_interface.rb
-- lib/gitlab/experiment/cache.rb
+- lib/gitlab/experiment
+- lib/gitlab/experiment/variant.rb
+- lib/gitlab/experiment/middleware.rb
+- lib/gitlab/experiment/cache
 - lib/gitlab/experiment/cache/redis_hash_store.rb
+- lib/gitlab/experiment/errors.rb
 - lib/gitlab/experiment/callbacks.rb
-- lib/gitlab/experiment/configuration.rb
+- lib/gitlab/experiment/rollout.rb
+- lib/gitlab/experiment/base_interface.rb
 - lib/gitlab/experiment/context.rb
-- lib/gitlab/experiment/cookies.rb
-- lib/gitlab/experiment/dsl.rb
 - lib/gitlab/experiment/engine.rb
-- lib/gitlab/experiment/rollout.rb
+- lib/gitlab/experiment/rspec.rb
+- lib/gitlab/experiment/rollout
 - lib/gitlab/experiment/rollout/random.rb
 - lib/gitlab/experiment/rollout/round_robin.rb
-- lib/gitlab/experiment/rspec.rb
-- lib/gitlab/experiment/variant.rb
+- lib/gitlab/experiment/rollout/percent.rb
+- lib/gitlab/experiment/cache.rb
 - lib/gitlab/experiment/version.rb
+- lib/gitlab/experiment/cookies.rb
+- lib/gitlab/experiment/configuration.rb
+- lib/gitlab/experiment/dsl.rb
+- LICENSE.txt
+- README.md
 homepage: https://gitlab.com/gitlab-org/gitlab-experiment
 licenses:
 - MIT
@@ -113,7 +130,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.17
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: GitLab experiment library built on top of scientist.