gitlab-labkit 0.40.0 → 0.41.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 570e79f377fc9cfa11a87177437e6f66a6ed78c94958ad999744034922011e31
-  data.tar.gz: a58252e9bb1792ac0e6ca7e65d565f49803e917eb845de065ffb4921b1bf405c
+  metadata.gz: 021f710ca320399402124ec377576c549cb5e323f59da70babd4e70f576cf12f
+  data.tar.gz: ef32fd2ac8e127847a7124f73155b8fc0d7397d2d07a563dde469d0f3c08b58d
 SHA512:
-  metadata.gz: eb4718ca04e0c5769180e3e23e3e658ea914a60c12142efc6f26bfc8f25b9a29d467c1c8fb582f23827c4e6cf3c9d72e65d7a7a469ab37465eb479f650e8269a
-  data.tar.gz: 90c9bff31da38826e4d60d6ac623f97257a78fbea63ea86aba8a15dd22df69e069ed628af48fc5f4695d58f1157c098f22a8e9676f97e8345522073349603bf5
+  metadata.gz: d6fa54d12f6fc16838d116316ca612ec5bc243e282b5b24ffca56547f9a4192e2ae59db05499cf18d4bb2d2f97c4295bb424dffadaa47f760c3614f8f6099e17
+  data.tar.gz: 6ed7ef8bc8a7fa9cfe212ef1329c4dd86ec5613db5e6b80b42cc8e432ba49f10b6af200fdd10a46fd0e63198be4fd061a3555627002de158950adf1a2060ae47

data/.copier-answers.yml

@@ -3,7 +3,7 @@
 # See the project for instructions on how to update the project
 #
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: v1.35.1
+_commit: v1.36.0
 _src_path: https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git
 ee_licensed: false
 golang: false

data/.gitlab-ci-asdf-versions.yml

@@ -1,5 +1,5 @@
 # DO NOT MANUALLY EDIT; Run ./scripts/update-asdf-version-variables.sh to update this
 variables:
-    GL_ASDF_RUBY_VERSION: "3.4.5"
-    GL_ASDF_SHELLCHECK_VERSION: "0.10.0"
+    GL_ASDF_RUBY_VERSION: "3.4.6"
+    GL_ASDF_SHELLCHECK_VERSION: "0.11"
     GL_ASDF_SHFMT_VERSION: "3.12"

data/.pre-commit-config.yaml

@@ -5,7 +5,7 @@
 # exclude: '^fixtures/'
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0  # renovate:managed
+    rev: v6.0.0  # renovate:managed
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -25,7 +25,7 @@ repos:
   # Documentation available at
   # https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/pre-commit.md
   - repo: https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks
-    rev: v2.85  # renovate:managed
+    rev: v2.92  # renovate:managed
 
     hooks:
       - id: shellcheck  # Run shellcheck for changed Shell files

data/.rubocop_todo.yml

@@ -257,7 +257,7 @@ RSpec/LetBeforeExamples:
 # Offense count: 20
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
-  Max: 7
+  Max: 8
 
 # Offense count: 24
 # Configuration parameters: EnforcedStyle, IgnoreSharedExamples.

data/.tool-versions

@@ -1,3 +1,3 @@
-ruby 3.4.5
+ruby 3.4.6
 shfmt 3.12
-shellcheck 0.10.0
+shellcheck 0.11

data/README.md

@@ -20,7 +20,7 @@ LabKit-Ruby provides functionality in a number of areas:
 
 1. `Labkit::Context` used for providing context information to log messages.
 1. `Labkit::Correlation` for accessing the correlation id. (Generated and propagated by `Labkit::Context`)
-1. `Labkit::CoveredExperience` for tracking covered experiences. More on the [README](./lib/labkit/covered_experiences/README.md).
+1. `Labkit::CoveredExperience` for tracking covered experiences. More on the [README](./lib/labkit/covered_experience/README.md).
 1. `Labkit::FIPS` for checking for FIPS mode and using FIPS-compliant algorithms.
 1. `Labkit::Logging` for sanitizing log messages.
 1. `Labkit::Metrics` for metrics. More on the [README](./lib/labkit/metrics/README.md).

data/lib/labkit/covered_experience/README.md

@@ -16,6 +16,23 @@ end
 
 This configuration affects all Covered Experience instances and their logging output.
 
+### Registry Path Configuration
+
+By default, covered experience definitions are loaded from the `config/covered_experiences` directory. You can configure a custom registry path:
+
+```ruby
+Labkit::CoveredExperience.configure do |config|
+  config.registry_path = "my/custom/path"
+end
+```
+
+This allows you to:
+- Store covered experience definitions in a different directory structure
+- Use different paths for different environments
+- Organize definitions according to your application's needs
+
+**Note:** The registry is automatically reset when the configuration changes, so the new path takes effect immediately.
+
 ### Covered Experience Definitions
 
 Covered experience definitions will be lazy loaded from the default directory (`config/covered_experiences`).
@@ -100,6 +117,40 @@ experience.checkpoint
 experience.complete
 ```
 
+#### Resuming Experiences
+
+You can resume a covered experience that was previously started and stored in the context. This is useful for distributed operations or when work spans multiple processes.
+
+Just like the start method, we can use a block to automatically complete a covered experience:
+
+```ruby
+# Resume an experience from context (with block)
+Labkit::CoveredExperience.resume(:merge_request_creation) do |experience|
+  # Continue the work from where it left off
+  finalize_merge_request
+
+  # Add checkpoints as needed
+  experience.checkpoint
+
+  send_notifications
+end
+```
+Or manually:
+
+```ruby
+# Resume an experience from context (manual control)
+experience = Labkit::CoveredExperience.resume(:merge_request_creation)
+
+# Continue the work
+finalize_merge_request
+experience.checkpoint
+
+# Complete the experience
+experience.complete
+```
+
+**Note:** The `resume` method loads the start time from the Labkit context. If no covered experience data exists in the context, it behaves the same as calling methods on an unstarted experience and safely ignores the operation.
+
 ### Error Handling
 
 When using the block form, errors are automatically captured:
@@ -131,4 +182,4 @@ end
 
 - In `development` and `test` environments, accessing a non-existent covered experience will raise a `NotFoundError`
 - In other environments, a null object is returned that safely ignores all method calls
-- Attempting to checkpoint or complete an unstarted experience will raise an `UnstartedError` in `development` and `test` environments
+- Attempting to checkpoint or complete an unstarted experience will safely ignore the operation

data/lib/labkit/covered_experience/current.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "labkit/covered_experience/experience"
+
+module Labkit
+  module CoveredExperience
+    # The `Current` class represents a container for the current set
+    # of `Labkit::CoveredExperience::Experience` instances started and
+    # not yet completed.
+    #
+    # It uses `ActiveSupport::CurrentAttributes` to provide a thread-safe way to
+    # store and access experiences throughout the request and background job lifecycle.
+    #
+    # Example usage:
+    #   Labkit::CoveredExperience::Current.active_experiences << my_experience
+    #   Labkit::CoveredExperience::Current.rehydrate("create_merge_request", "start_time" => "2025-08-22T10:02:15.237Z")
+    class Current < ActiveSupport::CurrentAttributes
+      AGGREGATION_KEY = 'labkit_covered_experiences'
+
+      attribute :_active_experiences
+
+      def active_experiences
+        self._active_experiences ||= {}
+      end
+
+      def rehydrate(experience_id, **data)
+        instance = Labkit::CoveredExperience.get(experience_id).rehydrate(data)
+        active_experiences[instance.id] = instance
+        instance
+      end
+    end
+  end
+end

data/lib/labkit/covered_experience/error.rb

@@ -3,7 +3,7 @@
 module Labkit
   module CoveredExperience
     CoveredExperienceError = Class.new(StandardError)
-    UnstartedError = Class.new(CoveredExperienceError)
     NotFoundError = Class.new(CoveredExperienceError)
+    ReservedKeywordError = Class.new(CoveredExperienceError)
   end
 end

data/lib/labkit/covered_experience/experience.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
+require 'active_support/hash_with_indifferent_access'
+require 'forwardable'
 require 'labkit/context'
+require 'labkit/covered_experience/current'
 require 'labkit/covered_experience/error'
 
 module Labkit
@@ -12,15 +15,48 @@ module Labkit
       async_slow: 300
     }.freeze
 
+    RESERVED_KEYWORDS = %w[
+      checkpoint
+      covered_experience
+      feature_category
+      urgency
+      start_time
+      checkpoint_time
+      end_time
+      elapsed_time_s
+      urgency_threshold_s
+      error
+      error_message
+      success
+    ].freeze
+
     # The `Experience` class represents a single Covered Experience
     # event to be measured and reported.
     class Experience
-      attr_reader :error
+      extend Forwardable
+
+      attr_reader :error, :start_time
 
       def initialize(definition)
         @definition = definition
       end
 
+      def id
+        @definition.covered_experience
+      end
+
+      # Rehydrate an Experience instance from serialized data.
+      #
+      # @param data [Hash] A hash of serialized data.
+      # @return [Experience]
+      def rehydrate(data = {})
+        @start_time = Time.iso8601(data["start_time"]) if data&.has_key?("start_time") && data["start_time"]
+        self
+      rescue ArgumentError
+        warn("Invalid #{id}, start_time: #{data['start_time']}")
+        self
+      end
+
       # Start the Covered Experience.
       #
       # @yield [self] When a block is provided, the experience will be completed automatically.
@@ -41,52 +77,59 @@ module Labkit
       #  experience.complete
       def start(**extra, &)
         @start_time = Time.now.utc
-        checkpoint_counter.increment(checkpoint: "start")
+        checkpoint_counter.increment(checkpoint: "start", **base_labels)
         log_event("start", **extra)
 
+        Labkit::CoveredExperience::Current.active_experiences[id] = self
+
         return self unless block_given?
 
-        begin
-          yield self
-          self
-        rescue StandardError => e
-          error!(e)
-          raise
-        ensure
-          complete(**extra)
-        end
+        completable(**extra, &)
       end
 
       # Checkpoint the Covered Experience.
       #
       # @param extra [Hash] Additional data to include in the log event
-      # @raise [UnstartedError] If the experience has not been started and RAILS_ENV is development or test.
       # @return [self]
       def checkpoint(**extra)
-        return unless ensure_started!
+        return self unless ensure_started!
 
         @checkpoint_time = Time.now.utc
-        checkpoint_counter.increment(checkpoint: "intermediate")
+        checkpoint_counter.increment(checkpoint: "intermediate", **base_labels)
         log_event("intermediate", **extra)
 
         self
       end
 
+      # Resume the Covered Experience.
+      #
+      # @yield [self] When a block is provided, the experience will be completed automatically.
+      # @param extra [Hash] Additional data to include in the log
+      def resume(**extra, &)
+        return self unless ensure_started!
+
+        checkpoint(checkpoint_action: 'resume', **extra)
+
+        return self unless block_given?
+
+        completable(**extra, &)
+      end
+
       # Complete the Covered Experience.
       #
       # @param extra [Hash] Additional data to include in the log event
-      # @raise [UnstartedError] If the experience has not been started and RAILS_ENV is development or test.
       # @return [self]
       def complete(**extra)
-        return unless ensure_started!
+        return self unless ensure_started! && ensure_incomplete!
 
         begin
           @end_time = Time.now.utc
         ensure
-          checkpoint_counter.increment(checkpoint: "end")
-          total_counter.increment(error: has_error?)
-          apdex_counter.increment(success: apdex_success?) unless has_error?
+          checkpoint_counter.increment(checkpoint: "end", **base_labels)
+          total_counter.increment(error: has_error?, **base_labels)
+          apdex_counter.increment(success: apdex_success?, **base_labels) unless has_error?
           log_event("end", **extra)
+          Labkit::CoveredExperience::Current.active_experiences.delete(id)
         end
 
         self
@@ -105,6 +148,12 @@ module Labkit
         !!@error
       end
 
+      def to_h
+        return {} unless ensure_started!
+
+        { id => { "start_time" => @start_time&.iso8601(3) } }
+      end
+
       private
 
       def base_labels
@@ -114,10 +163,28 @@ module Labkit
       def ensure_started!
         return @start_time unless @start_time.nil?
 
-        err = UnstartedError.new("Covered Experience #{@definition.covered_experience} not started")
+        warn("Covered Experience #{@definition.covered_experience} not started")
+        false
+      end
 
-        warn(err)
-        raise(err) if %w[development test].include?(ENV['RAILS_ENV'])
+      def completable(**extra, &)
+        begin
+          yield self
+        rescue StandardError => e
+          error!(e)
+          raise
+        ensure
+          complete(**extra)
+        end
+
+        self
+      end
+
+      def ensure_incomplete!
+        return true if @end_time.nil?
+
+        warn("Covered Experience #{@definition.covered_experience} already completed")
+        false
       end
 
       def urgency_threshold
@@ -125,6 +192,8 @@ module Labkit
       end
 
       def elapsed_time
+        return 0 unless @start_time
+
         last_time = @end_time || @checkpoint_time || @start_time
         last_time - @start_time
       end
@@ -136,36 +205,35 @@ module Labkit
       def checkpoint_counter
         @checkpoint_counter ||= Labkit::Metrics::Client.counter(
           :gitlab_covered_experience_checkpoint_total,
-          'Total checkpoints for covered experiences',
-          base_labels
+          'Total checkpoints for covered experiences'
         )
       end
 
       def total_counter
         @total_counter ||= Labkit::Metrics::Client.counter(
           :gitlab_covered_experience_total,
-          'Total covered experience events (success/failure)',
-          base_labels
+          'Total covered experience events (success/failure)'
         )
       end
 
       def apdex_counter
         @apdex_counter ||= Labkit::Metrics::Client.counter(
           :gitlab_covered_experience_apdex_total,
-          'Total covered experience apdex events',
-          base_labels
+          'Total covered experience apdex events'
         )
       end
 
       def log_event(event_type, **extra)
+        validate_extra_parameters!(extra)
+
         log_data = build_log_data(event_type, **extra)
         logger.info(log_data)
       end
 
       def build_log_data(event_type, **extra)
-        log_data = {
+        log_data = ActiveSupport::HashWithIndifferentAccess.new(
           checkpoint: event_type,
-          covered_experience: @definition.covered_experience,
+          covered_experience: id,
           feature_category: @definition.feature_category,
           urgency: @definition.urgency,
           start_time: @start_time,
@@ -173,8 +241,8 @@ module Labkit
           end_time: @end_time,
           elapsed_time_s: elapsed_time,
           urgency_threshold_s: urgency_threshold
-        }
-        log_data.merge!(extra) if extra
+        )
+        log_data.reverse_merge!(extra) if extra
 
         if has_error?
           log_data[:error] = true
@@ -186,8 +254,24 @@ module Labkit
         log_data
       end
 
-      def warn(exception)
-        logger.warn(component: self.class.name, message: exception.message)
+      def warn(err, **extra)
+        case err
+        when StandardError
+          logger.warn(component: self.class.name, message: err.message, **extra)
+        when String
+          logger.warn(component: self.class.name, message: err, **extra)
+        end
+      end
+
+      def validate_extra_parameters!(extra)
+        return if extra.empty?
+
+        reserved_keys = extra.keys.map(&:to_s) & RESERVED_KEYWORDS
+        return if reserved_keys.empty?
+
+        err = ReservedKeywordError.new("Reserved keywords found in extra parameters: #{reserved_keys.join(', ')}")
+
+        raise(err) if %w[development test].include?(ENV['RAILS_ENV'])
       end
 
       def logger

data/lib/labkit/covered_experience/null.rb

@@ -6,9 +6,14 @@ module Labkit
     class Null
       include Singleton
 
-      attr_reader :id, :description, :feature_category, :urgency
+      def id = 'null'
 
-      def start(*_args)
+      def start(**_extra)
+        yield self if block_given?
+        self
+      end
+
+      def resume(**_extra)
         yield self if block_given?
         self
       end
@@ -17,6 +22,8 @@ module Labkit
       def checkpoint(*_args) = self
       def complete(*_args) = self
       def error!(*_args) = self
+      def rehydrate(*_args, **_kwargs) = self
+      def to_h = {}
     end
   end
 end

data/lib/labkit/covered_experience.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'labkit/covered_experience/current'
 require 'labkit/covered_experience/error'
 require 'labkit/covered_experience/experience'
 require 'labkit/covered_experience/null'
@@ -15,10 +16,11 @@ module Labkit
   module CoveredExperience
     # Configuration class for CoveredExperience
     class Configuration
-      attr_accessor :logger
+      attr_accessor :logger, :registry_path
 
       def initialize
         @logger = Labkit::Logging::JsonLogger.new($stdout)
+        @registry_path = File.join("config", "covered_experiences")
       end
     end
 
@@ -33,28 +35,45 @@ module Labkit
 
       def configure
         yield(configuration) if block_given?
+        # Reset registry when configuration changes to pick up new registry_path
+        @registry = nil
       end
 
       def registry
-        @registry ||= Registry.new
+        @registry ||= Registry.new(dir: configuration.registry_path)
       end
 
       def reset
         @registry = nil
+        reset_configuration
       end
 
+      # Retrieves a covered experience using the experience_id.
+      # It retrieves from the current context when available,
+      # otherwise it instantiates a new experience with the definition
+      # from the registry.
+      #
+      # @param experience_id [String, Symbol] The ID of the experience to retrieve.
+      # @return [Experience, Null] The found experience or a Null object if not found (in production/staging).
       def get(experience_id)
-        definition = registry[experience_id]
+        find_current(experience_id) || raise_or_null(experience_id)
+      end
 
-        if definition
-          Experience.new(definition)
-        else
-          raise_or_null(experience_id)
-        end
+      # Starts a covered experience using the experience_id.
+      #
+      # @param experience_id [String, Symbol] The ID of the experience to start.
+      # @param extra [Hash] Additional data to include in the log event.
+      # @return [Experience, Null] The started experience or a Null object if not found (in production/staging).
+      def start(experience_id, **extra, &)
+        get(experience_id).start(**extra, &)
       end
 
-      def start(experience_id, &)
-        get(experience_id).start(&)
+      # Resumes a covered experience using the experience_id.
+      #
+      # @param experience_id [String, Symbol] The ID of the experience to resume.
+      # @return [Experience, Null] The started experience or a Null object if not found (in production/staging).
+      def resume(experience_id, **extra, &)
+        get(experience_id).resume(**extra, &)
       end
 
       private
@@ -64,6 +83,14 @@ module Labkit
 
         raise(NotFoundError, "Covered Experience #{experience_id} not found in the registry")
       end
+
+      def find_current(experience_id)
+        xp = Current.active_experiences[experience_id.to_s]
+        return xp unless xp.nil?
+
+        definition = registry[experience_id]
+        Experience.new(definition) if definition
+      end
     end
   end
 end

data/lib/labkit/logging/json_logger.rb

@@ -84,7 +84,7 @@ module Labkit
           if value.is_a?(Time)
             hash[key] = value.utc.iso8601(3)
           elsif value.is_a?(Hash)
-            format_time(value)
+            format_time!(value)
           end
         end
       end

data/lib/labkit/middleware/rack.rb

@@ -25,6 +25,8 @@ module Labkit
 
           [status, headers, response]
         end
+      ensure
+        reset_current_experiences
       end
 
       private
@@ -44,6 +46,27 @@ module Labkit
           .merge("version" => "1")
           .to_json
       end
+
+      # Reset Current experiences to prevent memory leaks and cross-request contamination.
+      #
+      # Rails applications automatically call ActiveSupport::CurrentAttributes.reset_all
+      # after each request via https://github.com/rails/rails/blob/2d4f445051b63853d48c642d0ab59ab026aa1d6a/activesupport/lib/active_support/railtie.rb,
+      # but we must handle other scenarios where this middleware might be used:
+      #
+      # 1. Non-Rails Rack applications (Sinatra, Grape, plain Rack apps)
+      # 2. Custom Rack stacks that don't include ActiveSupport::Railtie
+      # 3. Test environments where Rails middleware stack might be bypassed
+      # 4. Microservices or API-only applications with minimal middleware
+      # 5. Background job processors that use Rack but not Rails' full stack
+      #
+      # By explicitly resetting here, we ensure covered experiences are properly
+      # cleaned up regardless of the application framework or middleware configuration.
+      def reset_current_experiences
+        # Only reset if the Current class is loaded to avoid unnecessary dependencies
+        return unless defined?(Labkit::CoveredExperience::Current)
+
+        Labkit::CoveredExperience::Current.reset
+      end
     end
   end
 end

data/lib/labkit/middleware/sidekiq/client.rb

@@ -13,6 +13,7 @@ module Labkit
           @chain ||= ::Sidekiq::Middleware::Chain.new do |chain|
             chain.add Labkit::Middleware::Sidekiq::Context::Client
             chain.add Labkit::Middleware::Sidekiq::Tracing::Client if Labkit::Tracing.enabled?
+            chain.add Labkit::Middleware::Sidekiq::CoveredExperience::Client
           end
         end
 

data/lib/labkit/middleware/sidekiq/covered_experience/client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'labkit/covered_experience/current'
+
+module Labkit
+  module Middleware
+    module Sidekiq
+      module CoveredExperience
+        # This middleware for Sidekiq-client wraps scheduling jobs with covered
+        # experience context. It retrieves the current experiences and
+        # populates the job with them.
+        class Client
+          def call(worker_class, job, _queue, _redis_pool)
+            data = Labkit::CoveredExperience::Current.active_experiences.inject({}) do |data, (_, xp)|
+              xp.checkpoint(checkpoint_action: "sidekiq_job_scheduled", worker: worker_class.to_s)
+              data.merge!(xp.to_h)
+            end
+
+            job[Labkit::CoveredExperience::Current::AGGREGATION_KEY] = data unless data.empty?
+
+            yield
+          end
+        end
+      end
+    end
+  end
+end

data/lib/labkit/middleware/sidekiq/covered_experience/server.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Labkit
+  module Middleware
+    module Sidekiq
+      module CoveredExperience
+        # This middleware for Sidekiq-server rehydrates the current experiences
+        # serialized to the job
+        class Server
+          def call(_worker_class, job, _queue)
+            job[Labkit::CoveredExperience::Current::AGGREGATION_KEY]&.each do |experience_id, data|
+              xp = Labkit::CoveredExperience::Current.rehydrate(experience_id, **data)
+              xp.checkpoint(checkpoint_action: "sidekiq_job_started", worker: job["class"].to_s)
+            end
+
+            yield
+
+          ensure
+            Labkit::CoveredExperience::Current.reset
+          end
+        end
+      end
+    end
+  end
+end

data/lib/labkit/middleware/sidekiq/covered_experience.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Labkit
+  module Middleware
+    module Sidekiq
+      # This module contains all the sidekiq middleware regarding covered
+      # experiences
+      module CoveredExperience
+        autoload :Client, "labkit/middleware/sidekiq/covered_experience/client"
+        autoload :Server, "labkit/middleware/sidekiq/covered_experience/server"
+      end
+    end
+  end
+end

data/lib/labkit/middleware/sidekiq/server.rb

@@ -13,6 +13,7 @@ module Labkit
           @chain ||= ::Sidekiq::Middleware::Chain.new do |chain|
             chain.add Labkit::Middleware::Sidekiq::Context::Server
             chain.add Labkit::Middleware::Sidekiq::Tracing::Server if Labkit::Tracing.enabled?
+            chain.add Labkit::Middleware::Sidekiq::CoveredExperience::Server
           end
         end
 

data/lib/labkit/middleware/sidekiq.rb

@@ -7,6 +7,7 @@ module Labkit
       autoload :Client, "labkit/middleware/sidekiq/client"
       autoload :Server, "labkit/middleware/sidekiq/server"
       autoload :Context, "labkit/middleware/sidekiq/context"
+      autoload :CoveredExperience, "labkit/middleware/sidekiq/covered_experience"
       autoload :Tracing, "labkit/middleware/sidekiq/tracing"
     end
   end

data/lib/labkit/rspec/README.md

@@ -45,6 +45,17 @@ expect { subject }.to checkpoint_covered_experience('rails_request')
 expect { subject }.not_to checkpoint_covered_experience('rails_request')
 ```
 
+#### `resume_covered_experience`
+
+Tests that a covered experience is resumed (checkpoint=intermediate metric is incremented). This is an alias for `checkpoint_covered_experience` that provides more semantic meaning when testing code that resumes a covered experience previously started.
+
+```ruby
+expect { subject }.to resume_covered_experience('rails_request')
+
+# Test that it does NOT resume
+expect { subject }.not_to resume_covered_experience('rails_request')
+```
+
 #### `complete_covered_experience`
 
 Tests that a covered experience is completed with the expected metrics:

data/lib/labkit/rspec/matchers/covered_experience_matchers.rb

@@ -81,7 +81,7 @@ end
 #
 # Parameters:
 # - covered_experience_id: Required. The ID of the covered experience (e.g., 'rails_request')
-RSpec::Matchers.define :checkpoint_covered_experience do |covered_experience_id|
+RSpec::Matchers.define :checkpoint_covered_experience do |covered_experience_id, by: 1|
   include Labkit::RSpec::Matchers::CoveredExperience
 
   description { "checkpoint covered experience '#{covered_experience_id}'" }
@@ -97,12 +97,15 @@ RSpec::Matchers.define :checkpoint_covered_experience do |covered_experience_id|
     checkpoint_after = checkpoint_counter&.get(labels.merge(checkpoint: "intermediate")).to_i
     @checkpoint_change = checkpoint_after - checkpoint_before
 
-    @checkpoint_change == 1
+    # Automatic checkpoints can be created in-between depending on the context,
+    # such as pushing experiences to background jobs. For this reason, we check
+    # that the value increases by at least "by".
+    @checkpoint_change >= by
   end
 
   failure_message do
     "Failed to checkpoint covered experience '#{covered_experience_id}':\n" \
-      "expected checkpoint='intermediate' counter to increase by 1, but increased by #{@checkpoint_change}"
+      "expected checkpoint='intermediate' counter to increase by at least #{by}, but increased by #{@checkpoint_change}"
   end
 
   match_when_negated do |actual|
@@ -120,10 +123,13 @@ RSpec::Matchers.define :checkpoint_covered_experience do |covered_experience_id|
 
   failure_message_when_negated do
     "Expected covered experience '#{covered_experience_id}' NOT to checkpoint:\n" \
-      "expected checkpoint='intermediate' counter to increase by 0, but increased by #{@checkpoint_change}"
+      "expected checkpoint='intermediate' counter not to increase, but increased by #{@checkpoint_change}"
   end
 end
 
+# Alias for checkpoint_covered_experience matcher
+RSpec::Matchers.alias_matcher :resume_covered_experience, :checkpoint_covered_experience
+
 # Matcher for verifying CoveredExperience completion metrics instrumentation.
 #
 # Usage:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 0.40.0
+  version: 0.41.2
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -460,6 +460,7 @@ files:
 - lib/labkit/correlation/grpc/server_interceptor.rb
 - lib/labkit/covered_experience.rb
 - lib/labkit/covered_experience/README.md
+- lib/labkit/covered_experience/current.rb
 - lib/labkit/covered_experience/error.rb
 - lib/labkit/covered_experience/experience.rb
 - lib/labkit/covered_experience/null.rb
@@ -485,6 +486,9 @@ files:
 - lib/labkit/middleware/sidekiq/context.rb
 - lib/labkit/middleware/sidekiq/context/client.rb
 - lib/labkit/middleware/sidekiq/context/server.rb
+- lib/labkit/middleware/sidekiq/covered_experience.rb
+- lib/labkit/middleware/sidekiq/covered_experience/client.rb
+- lib/labkit/middleware/sidekiq/covered_experience/server.rb
 - lib/labkit/middleware/sidekiq/server.rb
 - lib/labkit/middleware/sidekiq/tracing.rb
 - lib/labkit/middleware/sidekiq/tracing/client.rb