gitlab-labkit 0.40.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 570e79f377fc9cfa11a87177437e6f66a6ed78c94958ad999744034922011e31
-  data.tar.gz: a58252e9bb1792ac0e6ca7e65d565f49803e917eb845de065ffb4921b1bf405c
+  metadata.gz: 762df6d0e3348526c7b49929a3a6cdd82db05c80a9d83569a76bd10ddb131ca2
+  data.tar.gz: 0affeb965dd17cfc202a0b64419d46bb92419a051a70972cbab5d57e5844d027
 SHA512:
-  metadata.gz: eb4718ca04e0c5769180e3e23e3e658ea914a60c12142efc6f26bfc8f25b9a29d467c1c8fb582f23827c4e6cf3c9d72e65d7a7a469ab37465eb479f650e8269a
-  data.tar.gz: 90c9bff31da38826e4d60d6ac623f97257a78fbea63ea86aba8a15dd22df69e069ed628af48fc5f4695d58f1157c098f22a8e9676f97e8345522073349603bf5
+  metadata.gz: c703503bc9cf08155d72a0ffc61f7f8cc2c573353d67382e7b4d7b22ea554c2a14ee2e2d04f8804696fa95584843cd4a342cbcdb5e9cb8ac775bd0d36df006b3
+  data.tar.gz: 2a598ffe29d7382689637c605db8ba721c993e3fc4b033176b273b99515033577b16d82961007bb9e99da3feac5ec2419e58c7a45b354dfd820e4d9bfa9baa4b

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_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
 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 (raises `UnstartedError` in development/test environments, or safely ignores in other environments).
+
 ### Error Handling
 
 When using the block form, errors are automatically captured:

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

@@ -4,6 +4,8 @@ module Labkit
   module CoveredExperience
     CoveredExperienceError = Class.new(StandardError)
     UnstartedError = Class.new(CoveredExperienceError)
+    CompletedError = 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,20 +77,14 @@ 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.
@@ -66,12 +96,26 @@ module Labkit
         return 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 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
@@ -79,14 +123,16 @@ module Labkit
       # @return [self]
       def complete(**extra)
         return unless ensure_started!
+        return unless 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 +151,12 @@ module Labkit
         !!@error
       end
 
+      def to_h
+        return {} unless ensure_started!
+
+        { id => { "start_time" => @start_time&.iso8601(3) } }
+      end
+
       private
 
       def base_labels
@@ -120,6 +172,28 @@ module Labkit
         raise(err) if %w[development test].include?(ENV['RAILS_ENV'])
       end
 
+      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?
+
+        err = CompletedError.new("Covered Experience #{@definition.covered_experience} already completed")
+
+        warn(err)
+        raise(err) if %w[development test].include?(ENV['RAILS_ENV'])
+      end
+
       def urgency_threshold
         URGENCY_THRESHOLDS_IN_SECONDS[@definition.urgency.to_sym]
       end
@@ -136,36 +210,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 +246,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 +259,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.0
 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