gitlab-experiment 0.6.1 → 0.6.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d1ad31e8b977491ccdd1a9d21fc348482d3942c80a3e2935a6ccabc515b4243
-  data.tar.gz: bdf9a4b67bb2b5a72931c081fed88ac246853a2e90f4f7f5c08bf7bdb9d8f55e
+  metadata.gz: 9651e4cc4941d879e7c006f5865ff71989babd942bfcc09a86eb5be89f17e38c
+  data.tar.gz: d23055b9c808ae680c05762d60a569306069578a8555f87daf816a717cef0c28
 SHA512:
-  metadata.gz: dc1cc5077144d4e5514b6804599bba8e6829ad6472e5e362cde88940995b174f9989733fea17da91be92dc172694a4394ee0db7974efba8d6eb4e77e769a57ee
-  data.tar.gz: 958cf74fa36b1588fd7f83776e87c7f8c92120cb8a6d421c09a4bd207adffdfcfe69ea295dd1e6a49d371225988f6fde3f559baf64d755a0c9176a33e7efddca
+  metadata.gz: af40d50563c3938f089d415ebece34be76a79f8b1c13f7f5a4d6c62f035a7fe07147a4ab9ad475f00372d94be7b5c35f6c54ee2f866c3b0875748774cb04f1bb
+  data.tar.gz: fd4b8c69bc49351a7050d5ab6665c42855cf1d26b18e4a4e1983fbbeba2a8487b1523b6d1f824f0862d0fd16d425565eaf4ce179120a2e55bbbbeef53ae03a2f

data/README.md

@@ -47,7 +47,7 @@ We'll name our experiment `notification_toggle`. This name is prefixed based on
 
 When you implement an experiment you'll need to provide a name, and a context. The name can show up in tracking calls, and potentially other aspects. The context determines the variant assigned, and should be consistent between calls. We'll discuss migrating context in later examples.
 
-A context "key" represents the unique id of a context. It allows us to give the same experience between different calls to the experiment and can be used in caching.
+A context "key" represents the unique id of a context. It allows us to give the same experience between different calls to the experiment and can be used in caching. This is how an experiment remains "sticky" to a given context.
 
 Now in our experiment we're going to render one of two views: the control will be our current view, and the candidate will be the new toggle button with a confirmation flow.
 
@@ -74,6 +74,12 @@ experiment(:notification_toggle, actor: user) do |e|
 end
 ```
 
+You can specify what the experiment should be "sticky" to by providing a `:sticky_to` option. By default this will be the entire context provided, but this can be overridden manually if needed.
+
+```ruby
+experiment(:notification_toggle, actor: user, project: project, sticky_to: project) #...
+```
+
 Understanding how an experiment can change behavior is important in evaluating its performance.
 
 To this end, we track events that are important by calling the same experiment elsewhere in code. By using the same context, you'll have consistent behavior and the ability to track events to it.

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

@@ -56,6 +56,16 @@ Gitlab::Experiment.configure do |config|
   #   '/-/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.
   #
   # Expected to return a boolean value.

data/lib/gitlab/experiment/base_interface.rb

@@ -29,7 +29,8 @@ module Gitlab
 
         def from_param(id)
           %r{/?(?<name>.*):(?<key>.*)$} =~ id
-          Gitlab::Experiment.new(name).tap { |e| e.context.key(key) }
+          name = CGI.unescape(name) if name
+          constantize(name).new(name).tap { |e| e.context.key(key) }
         end
       end
 

data/lib/gitlab/experiment/callbacks.rb

@@ -9,6 +9,7 @@ module Gitlab
       include ActiveSupport::Callbacks
 
       included do
+        define_callbacks(:run)
         define_callbacks(:unsegmented)
         define_callbacks(:segmentation_check)
         define_callbacks(:exclusion_check, skip_after_callbacks_if_terminated: true)

data/lib/gitlab/experiment/configuration.rb

@@ -39,17 +39,19 @@ module Gitlab
 
       # The default base path that the middleware (or rails engine) will be
       # mounted.
-      @mount_at = '/experiment'
+      @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.
@@ -88,6 +90,7 @@ module Gitlab
           :context_key_bit_length,
           :mount_at,
           :default_rollout,
+          :redirect_url_validator,
           :inclusion_resolver,
           :tracking_behavior,
           :publishing_behavior

data/lib/gitlab/experiment/context.rb

@@ -27,6 +27,7 @@ module Gitlab
 
         value = value.dup # dup so we don't mutate
         reinitialize(value.delete(:request))
+        key(value.delete(:sticky_to))
 
         @value.merge!(process_migrations(value))
       end
@@ -34,7 +35,7 @@ module Gitlab
       def key(key = nil)
         return @key || @experiment.key_for(value) if key.nil?
 
-        @key = key
+        @key = @experiment.key_for(key)
       end
 
       def trackable?
@@ -61,16 +62,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,35 +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
 
-        return unless defined?(ActionMailer)
+      initializer('gitlab_experiment.include_dsl') { include_dsl }
+      initializer('gitlab_experiment.mount_engine') { |app| mount_engine(app, Configuration.mount_at) }
 
-        ActionMailer::Base.include(Dsl)
-        ActionMailer::Base.helper_method(:experiment)
+      private
+
+      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
 
-      def add_middleware(app, base_path)
-        return if base_path.blank?
+      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, base_path)
+        app.config.middleware.use(Middleware, mount_at)
         app.routes.append do
-          direct :experiment_redirect do |experiment, to_url|
-            [base_path, experiment.to_param].join('/') + "?#{to_url}"
+          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
-
-      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

@@ -4,5 +4,6 @@ module Gitlab
   class Experiment
     Error = Class.new(StandardError)
     InvalidRolloutRules = Class.new(Error)
+    NestingError = Class.new(Error)
   end
 end

data/lib/gitlab/experiment/middleware.rb

@@ -6,8 +6,8 @@ module Gitlab
       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 }, []]
+        experiment = Gitlab::Experiment.from_param(id)
+        [303, { 'Location' => experiment.process_redirect_url(url) || raise(Error, 'not redirecting') }, []]
       end
 
       def initialize(app, base_path)

data/lib/gitlab/experiment/nestable.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Gitlab
+  class Experiment
+    module Nestable
+      extend ActiveSupport::Concern
+
+      included do
+        set_callback :run, :around, :manage_nested_stack
+      end
+
+      def nest_experiment(other)
+        raise NestingError, "unable to nest the #{other.name} experiment within the #{name} experiment"
+      end
+
+      private
+
+      def manage_nested_stack
+        Stack.push(self)
+        yield
+      ensure
+        Stack.pop
+      end
+
+      class Stack
+        include Singleton
+
+        @stack = []
+
+        class << self
+          delegate :pop, :length, :size, :[], to: :@stack
+
+          def push(instance)
+            @stack.last&.nest_experiment(instance)
+            @stack.push(instance)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/experiment/rspec.rb

@@ -2,6 +2,10 @@
 
 module Gitlab
   class Experiment
+    module TestBehaviors
+      autoload :Trackable, 'gitlab/experiment/test_behaviors/trackable.rb'
+    end
+
     module RSpecHelpers
       def stub_experiments(experiments, times = nil)
         experiments.each { |experiment| wrapped_experiment(experiment, times) }
@@ -82,7 +86,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,
@@ -234,6 +238,10 @@ RSpec.configure do |config|
 
   config.before(:each, :experiment) do
     RequestStore.clear!
+
+    if defined?(Gitlab::Experiment::TestBehaviors::TrackedStructure)
+      Gitlab::Experiment::TestBehaviors::TrackedStructure.reset!
+    end
   end
 
   config.include Gitlab::Experiment::RSpecMatchers, :experiment

data/lib/gitlab/experiment/test_behaviors/trackable.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Gitlab
+  class Experiment
+    module TestBehaviors
+      module Trackable
+        private
+
+        def manage_nested_stack
+          TrackedStructure.push(self)
+          super
+        ensure
+          TrackedStructure.pop
+        end
+      end
+
+      class TrackedStructure
+        include Singleton
+
+        # dependency tracking
+        @flat = {}
+        @stack = []
+
+        # structure tracking
+        @tree = { name: nil, count: 0, children: {} }
+        @node = @tree
+
+        class << self
+          def reset!
+            # dependency tracking
+            @flat = {}
+            @stack = []
+
+            # structure tracking
+            @tree = { name: nil, count: 0, children: {} }
+            @node = @tree
+          end
+
+          def hierarchy
+            @tree[:children]
+          end
+
+          def dependencies
+            @flat
+          end
+
+          def push(instance)
+            # dependency tracking
+            @flat[instance.name] = ((@flat[instance.name] || []) + @stack.map(&:name)).uniq
+            @stack.push(instance)
+
+            # structure tracking
+            @last = @node
+            @node = @node[:children][instance.name] ||= { name: instance.name, count: 0, children: {} }
+            @node[:count] += 1
+          end
+
+          def pop
+            # dependency tracking
+            @stack.pop
+
+            # structure tracking
+            @node = @last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/experiment/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   class Experiment
-    VERSION = '0.6.1'
+    VERSION = '0.6.5'
   end
 end

data/lib/gitlab/experiment.rb

@@ -19,6 +19,7 @@ require 'gitlab/experiment/cookies'
 require 'gitlab/experiment/context'
 require 'gitlab/experiment/dsl'
 require 'gitlab/experiment/middleware'
+require 'gitlab/experiment/nestable'
 require 'gitlab/experiment/variant'
 require 'gitlab/experiment/version'
 require 'gitlab/experiment/engine' if defined?(Rails::Engine)
@@ -28,6 +29,7 @@ module Gitlab
     include BaseInterface
     include Cache
     include Callbacks
+    include Nestable
 
     class << self
       def default_rollout(rollout = nil, options = {})
@@ -103,7 +105,9 @@ module Gitlab
     end
 
     def run(variant_name = nil)
-      @result ||= super(variant(variant_name).name)
+      return @result if context.frozen?
+
+      @result = run_callbacks(:run) { super(variant(variant_name).name) }
     rescue Scientist::BehaviorMissing => e
       raise Error, e
     end
@@ -120,6 +124,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
@@ -148,6 +159,8 @@ module Gitlab
         return instance_exec(source, seed, &block)
       end
 
+      return source if source.is_a?(String)
+
       source = source.keys + source.values if source.is_a?(Hash)
 
       ingredients = Array(source).map { |v| identify(v) }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.5
 platform: ruby
 authors:
 - GitLab
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-22 00:00:00.000000000 Z
+date: 
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -65,38 +65,55 @@ 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/test_behaviors
+- lib/gitlab/experiment/test_behaviors/trackable.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/nestable.rb
 - lib/gitlab/experiment/context.rb
-- 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/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
@@ -116,7 +133,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.20
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: GitLab experiment library built on top of scientist.