gitlab-experiment 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e34a0534e252b90b635ed280483d18741c2ac7034f5aadc68f14812b77baa0e7
-  data.tar.gz: 96bb108c2888ffc97f28b59b00b3a631d1370782e9108a06e22bb8492ac79bef
+  metadata.gz: 453f39a65f699c77881655a8dbfd40d15133baa47e063b76278e2953c4b1de7c
+  data.tar.gz: 3cd7e33850a1d0725bd7f4c82bbcd9d8769c01c1e6663226dcc07acdf68d24ec
 SHA512:
-  metadata.gz: 2481560efcb4fafd00f64cadb7fd4199607cec596e168ce4eb72334f17ad812407441cb492412680caae3c5e7ff699cb455092dd4ae750c942badd9f3b52b304
-  data.tar.gz: 3996ae0f5626023540ae3ad4aeaae2127407626ee369ce2edfa829379c074672bfc9840ecf96baec55d800e648c1bb18ece6fb54c96d3e1e03d0cabf757f6fce
+  metadata.gz: 9ba7cc88703891e0ff10a885b55e0f59911459ffa6de2a7102dececf803cf27ea0d0e62912409b543a537c6df1266e403c18d4aa96d6767cfa1f7ae64d638dd3
+  data.tar.gz: 5f292e0a952811292354e1d9e84705b88eb225b79819bdb00b3fcf55f7a06754ff87a8502ecd8b5016278629a2c6d83609566dad373bdb2f11d44eca4ed7cdd3

data/README.md

@@ -680,11 +680,17 @@ end
 ```
 
 **Behavior with `only_assigned: true`:**
-- ✅ If user already assigned → returns their cached variant
-- ✅ If user not assigned → returns control, no tracking
+- ✅ If user has a cached assignment (control or candidate) → returns that variant and tracks
+- ✅ If user has no cached assignment → returns control, no tracking
 - ✅ Experiment reach stays controlled
 - ✅ Perfect for multi-page experimental experiences
 
+> **Note:** `only_assigned: true` relies on cached assignments. Control variants are cached
+> by default (see [Advanced: Caching Configuration](#advanced-caching-configuration)) so that
+> bucketed control users are included in `only_assigned` tracking. If you set
+> `cache_control: false`, control users will appear unassigned at secondary sites and be
+> excluded from tracking there.
+
 **Real-world use cases:**
 - **Post-signup experiences**: Assign at signup, show features throughout the app
 - **Gradual feature expansion**: Roll out to 5%, then add more touchpoints without expanding population
@@ -1318,6 +1324,34 @@ documented in its implementation.
 
 **Important:** Caching changes how rollout strategies behave. Once cached, subsequent calls return the cached value regardless of rollout strategy changes.
 
+**Control variant caching:**
+
+By default, the gem caches `:control` assignments alongside variant assignments. This is what
+makes `only_assigned: true` lookups include bucketed control users -- without it, control
+users would appear unassigned at secondary tracking sites and would be silently excluded.
+
+```ruby
+# Disable globally (don't cache :control)
+Gitlab::Experiment.configure do |config|
+  config.cache_control = false
+end
+
+# Or override per-rollout
+class MyExperiment < ApplicationExperiment
+  default_rollout :percent, cache_control: false
+end
+```
+
+The `Random` rollout strategy intentionally opts out of caching `:control` regardless of this
+setting, because its convergence model depends on re-rolling control assignments on every
+visit until a non-control variant is picked.
+
+**Operational note:** With control caching enabled, `Percent` and `RoundRobin` cache hashes
+grow with every bucketed user, not just users assigned to a candidate variant. For
+long-running experiments the cache will be roughly `1 / candidate_percentage` the size it
+would have been before. Plan periodic cleanup using your store's deletion API -- for the
+`RedisHashStore`, that's `experiment.cache.store.clear(key: experiment.name)`.
+
 ### Advanced: Custom Rollout Strategies
 
 Build custom integrations with your existing infrastructure:

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

@@ -22,6 +22,20 @@ Gitlab::Experiment.configure do |config|
   # Use `nil` for no caching.
   config.cache = nil
 
+  # Cache `:control` assignments alongside variant assignments.
+  #
+  # When set to true (the default), bucketed control users are cached and
+  # therefore visible to `only_assigned: true` tracking calls. Set to false
+  # to skip caching control -- control users will be treated as unassigned
+  # at `only_assigned` sites and excluded from tracking there.
+  #
+  # Can be overridden per-rollout:
+  #
+  # class ExampleExperiment < ApplicationExperiment
+  #   default_rollout :percent, cache_control: false
+  # end
+  config.cache_control = true
+
   # The domain to use on cookies.
   #
   # When not set, it uses the current host. If you want to provide specific

data/lib/gitlab/experiment/configuration.rb

@@ -30,6 +30,21 @@ module Gitlab
       # Use `nil` for no caching.
       @cache = nil
 
+      # Whether `:control` assignments should be written to the cache.
+      #
+      # When true (default), control variants are cached alongside other
+      # variants, which is required for `only_assigned: true` tracking to
+      # work correctly for the control arm of an experiment.
+      #
+      # When false, control variants are not cached. This preserves the
+      # behavior of versions prior to this option being introduced. Any
+      # experiment using `only_assigned: true` will silently exclude
+      # control users from tracking.
+      #
+      # Individual rollouts can override this via the `cache_control:`
+      # option, e.g. `default_rollout :percent, cache_control: false`.
+      @cache_control = true
+
       # The domain to use on cookies.
       #
       # When not set, it uses the current host. If you want to provide specific
@@ -193,6 +208,7 @@ module Gitlab
           :base_class,
           :strict_registration,
           :cache,
+          :cache_control,
           :cookie_domain,
           :cookie_name,
           :secure_cookie,
@@ -213,6 +229,19 @@ module Gitlab
           @default_rollout = Rollout.resolve(*args)
         end
 
+        def cache_control=(value) # rubocop:disable Lint/DuplicateMethods
+          if value != true
+            deprecated(
+              :cache_control,
+              "setting `cache_control` to a non-true value is deprecated and will be removed in version 2.0. " \
+                "Control variants will always be cached.",
+              version: '1.4'
+            )
+          end
+
+          @cache_control = value
+        end
+
         # Internal warning helpers.
 
         def deprecated(*args, version:, stack: 0)

data/lib/gitlab/experiment/dsl.rb

@@ -7,10 +7,19 @@ module Gitlab
         klass.include(self).tap { |base| base.helper_method(:experiment) if with_helper }
       end
 
+      # An explicit `request:` keyword argument always takes precedence; when
+      # present, no auto-detection runs.
+      #
+      # Otherwise, `request` is auto-detected through implicit_experiment_request in this order:
+      #   1. A `request` method on `self` (the controller pattern).
+      #   2. A `@request` instance variable on `self` (the service pattern).
+      #
+      # Callers with `request` as a pure local variable should pass
+      # `request: request` explicitly.
       def experiment(name, variant_name = nil, **context, &block)
         raise ArgumentError, 'name is required' if name.nil?
 
-        context[:request] ||= request if respond_to?(:request)
+        context[:request] ||= implicit_experiment_request
 
         base = Configuration.base_class.constantize
         klass = base.constantize(name) || base
@@ -20,6 +29,16 @@ module Gitlab
 
         instance.context.frozen? ? instance.run : instance.tap(&:run)
       end
+
+      private
+
+      def implicit_experiment_request
+        if respond_to?(:request)
+          request
+        elsif instance_variable_defined?(:@request)
+          instance_variable_get(:@request)
+        end
+      end
     end
   end
 end

data/lib/gitlab/experiment/errors.rb

@@ -7,6 +7,7 @@ module Gitlab
     UnregisteredExperiment = Class.new(Error)
     ExistingBehaviorError = Class.new(Error)
     BehaviorMissingError = Class.new(Error)
+    ControlNotCachedError = Class.new(Error)
 
     class NestingError < Error
       def initialize(experiment:, nested_experiment:)

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

@@ -3,9 +3,12 @@
 # The random rollout strategy will randomly assign a variant when the context is determined to be within the experiment
 # group.
 #
-# If caching is enabled this is a predicable and consistent assignment that will eventually assign a variant (since
-# control isn't cached) but if caching isn't enabled, assignment will be random each time.
+# If caching is enabled this is a predictable and consistent assignment that will eventually assign a non-control
+# variant. This relies on the strategy intentionally NOT caching control assignments -- so when a context is sampled
+# into control, it gets re-rolled on the next visit until it lands on a non-control variant, at which point the
+# assignment is cached and stable. Without caching, assignment is random on every call.
 #
+# This is the only rollout that opts out of caching control: every other rollout caches whatever variant it resolves to.
 # Example configuration usage:
 #
 # config.default_rollout = Gitlab::Experiment::Rollout::Random.new
@@ -28,7 +31,10 @@ module Gitlab
         protected
 
         def execute_assignment
-          behavior_names.sample # pick a random variant
+          result = behavior_names.sample # pick a random variant
+          # Drop :control so it's never cached, even if cache_control is true.
+          # The context will be re-rolled on the next visit and eventually converge on a non-control variant.
+          result == :control ? nil : result
         end
       end
     end

data/lib/gitlab/experiment/rollout.rb

@@ -31,6 +31,15 @@ module Gitlab
 
           @experiment = experiment
           @options = options
+
+          return if !options.key?(:cache_control) || options[:cache_control] == true
+
+          Configuration.deprecated(
+            :cache_control,
+            "setting `cache_control` to a non-true value on a rollout is deprecated and " \
+              "will be removed in version 2.0. Control variants will always be cached.",
+            version: '1.4'
+          )
         end
 
         def enabled?
@@ -41,7 +50,17 @@ module Gitlab
           validate! # allow the rollout strategy to validate itself
 
           assignment = execute_assignment
-          assignment == :control ? nil : assignment # avoid caching control by returning nil
+          # Cache control assignments unless explicitly opted out. The per-rollout `cache_control:`
+          # option takes precedence over the global `Configuration.cache_control` default.
+          return assignment if cache_control_enabled?
+
+          assignment == :control ? nil : assignment
+        end
+
+        # Returns true when this rollout caches `:control` assignments. Per-rollout
+        # `cache_control:` option takes precedence over the global default.
+        def cache_control_enabled?
+          options.fetch(:cache_control, Configuration.cache_control)
         end
 
         private

data/lib/gitlab/experiment/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   class Experiment
-    VERSION = '1.3.0'
+    VERSION = '1.5.0'
   end
 end

data/lib/gitlab/experiment.rb

@@ -166,7 +166,16 @@ module Gitlab
     end
 
     def only_assigned?
-      !!context.only_assigned && find_variant.blank?
+      return false unless context.only_assigned
+
+      unless rollout.cache_control_enabled?
+        raise ControlNotCachedError,
+          "`only_assigned: true` requires `cache_control: true`, but the rollout for " \
+            "experiment `#{name}` has it disabled. Control users would be silently excluded " \
+            "from tracking. Enable cache_control or remove `only_assigned: true`."
+      end
+
+      find_variant.blank?
     end
 
     def should_track?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-25 00:00:00.000000000 Z
+date: 2026-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport