gitlab-experiment 0.5.4 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d7bc7a1946d06b5188ccfe761342209779f75cf635d894bb8743519ff2830dc
-  data.tar.gz: 7a5c347f8b58e5caa2fe814ce013dbf1ca71f6e017148528a0ff2ca74bd562de
+  metadata.gz: 0d1ad31e8b977491ccdd1a9d21fc348482d3942c80a3e2935a6ccabc515b4243
+  data.tar.gz: bdf9a4b67bb2b5a72931c081fed88ac246853a2e90f4f7f5c08bf7bdb9d8f55e
 SHA512:
-  metadata.gz: '01927d9db97ad4b087d445db642aa39615faa68322e2bd0e0b82ae99441478bae3f1939b94956218121fe52d01f432836ba272d0b1ff052537c80f0d0ff107b3'
-  data.tar.gz: f53702ea5bb97fe6c73427850534b9e156744336a37029dce2b96926b70b7a5c4959708ac626f6ac0435125ad4ffe62f2ba9fd528f756af811c6ff66abc47846
+  metadata.gz: dc1cc5077144d4e5514b6804599bba8e6829ad6472e5e362cde88940995b174f9989733fea17da91be92dc172694a4394ee0db7974efba8d6eb4e77e769a57ee
+  data.tar.gz: 958cf74fa36b1588fd7f83776e87c7f8c92120cb8a6d421c09a4bd207adffdfcfe69ea295dd1e6a49d371225988f6fde3f559baf64d755a0c9176a33e7efddca

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,31 @@ 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'
 
   # Logic this project uses to determine inclusion in a given experiment.
   #
@@ -80,17 +105,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)
@@ -139,11 +143,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,11 @@ module Gitlab
 
           experiment_name(name).classify.safe_constantize || Configuration.base_class.constantize
         end
+
+        def from_param(id)
+          %r{/?(?<name>.*):(?<key>.*)$} =~ id
+          Gitlab::Experiment.new(name).tap { |e| e.context.key(key) }
+        end
       end
 
       def initialize(name = nil, variant_name = nil, **context)
@@ -45,9 +50,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,6 +31,16 @@ 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 = '/experiment'
+
       # Logic this project uses to determine inclusion in a given experiment.
       # Expected to return a boolean value.
       @inclusion_resolver = lambda do |requested_variant|
@@ -47,24 +57,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 +84,13 @@ module Gitlab
           :base_class,
           :cache,
           :cookie_domain,
+          :context_key_secret,
+          :context_key_bit_length,
+          :mount_at,
           :default_rollout,
           :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, *)

data/lib/gitlab/experiment/engine.rb

@@ -15,7 +15,21 @@ module Gitlab
         ActionMailer::Base.helper_method(:experiment)
       end
 
+      def add_middleware(app, base_path)
+        return if base_path.blank?
+
+        app.config.middleware.use(Middleware, base_path)
+        app.routes.append do
+          direct :experiment_redirect do |experiment, to_url|
+            [base_path, experiment.to_param].join('/') + "?#{to_url}"
+          end
+        end
+      end
+
       config.after_initialize { include_dsl }
+      initializer 'gitlab_experiment.add_middleware' do |app|
+        add_middleware(app, Configuration.mount_at)
+      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?
+
+        Gitlab::Experiment.from_param(id).tap { |e| e.track('visited', url: url) }
+        [303, { 'Location' => url }, []]
+      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/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.1'
   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.1
 platform: ruby
 authors:
 - GitLab
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-05-05 00:00:00.000000000 Z
+date: 2021-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -88,7 +88,10 @@ files:
 - lib/gitlab/experiment/cookies.rb
 - lib/gitlab/experiment/dsl.rb
 - lib/gitlab/experiment/engine.rb
+- lib/gitlab/experiment/errors.rb
+- lib/gitlab/experiment/middleware.rb
 - lib/gitlab/experiment/rollout.rb
+- lib/gitlab/experiment/rollout/percent.rb
 - lib/gitlab/experiment/rollout/random.rb
 - lib/gitlab/experiment/rollout/round_robin.rb
 - lib/gitlab/experiment/rspec.rb
@@ -113,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.17
+rubygems_version: 3.2.20
 signing_key: 
 specification_version: 4
 summary: GitLab experiment library built on top of scientist.