gitlab-labkit 0.39.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 639ab73c3db48ed9078b0ae3743b5031d3d3e89dfde6aff9c65818b9aece82cb
-  data.tar.gz: ab65ac7320604017406ea64242c9dba98665ed12ad0f1268820e75031c301452
+  metadata.gz: 762df6d0e3348526c7b49929a3a6cdd82db05c80a9d83569a76bd10ddb131ca2
+  data.tar.gz: 0affeb965dd17cfc202a0b64419d46bb92419a051a70972cbab5d57e5844d027
 SHA512:
-  metadata.gz: 14feead5381e4d99a08cac69768dace5080d394c7267cc4c90fc44d0b5839b24838a16469e627f086a2731ac972f38729cb28cec96e84c2ac0ba5d1c27cc4eeb
-  data.tar.gz: aaae5ce7dbd8454862ce64a93a73280931802575213cfe18c35dee3a7edb410a240937da508b30c2cabe5dbefb0e3e534cbbd2c5a1428dcc2b6b8e90110392d8
+  metadata.gz: c703503bc9cf08155d72a0ffc61f7f8cc2c573353d67382e7b4d7b22ea554c2a14ee2e2d04f8804696fa95584843cd4a342cbcdb5e9cb8ac775bd0d36df006b3
+  data.tar.gz: 2a598ffe29d7382689637c605db8ba721c993e3fc4b033176b273b99515033577b16d82961007bb9e99da3feac5ec2419e58c7a45b354dfd820e4d9bfa9baa4b

data/.copier-answers.yml

@@ -3,10 +3,11 @@
 # See the project for instructions on how to update the project
 #
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: v1.31.0
+_commit: v1.35.1
 _src_path: https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git
 ee_licensed: false
 golang: false
+helm: false
 initial_codeowners: '@reprazent @andrewn @mkaeppler @ayufan'
 jsonnet: false
 project_name: labkit-ruby

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.4"
-    GL_ASDF_SHELLCHECK_VERSION: "0.10.0"
-    GL_ASDF_SHFMT_VERSION: "3.11.0"
+    GL_ASDF_RUBY_VERSION: "3.4.5"
+    GL_ASDF_SHELLCHECK_VERSION: "0.11"
+    GL_ASDF_SHFMT_VERSION: "3.12"

data/.gitlab-ci.yml

@@ -19,19 +19,13 @@ include:
   # It includes standard checks, gitlab-scanners, validations and release processes
   # common to all projects using this template library.
   # see https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/templates/standard.md
-  - project: "gitlab-com/gl-infra/common-ci-tasks"
-    ref: v2.77 # renovate:managed
-    file: templates/standard.yml
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/standard-build@v2.78
 
   # Runs rspec tests and rubocop on the project
   # see https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/templates/ruby.md
-  - project: "gitlab-com/gl-infra/common-ci-tasks"
-    ref: v2.77 # renovate:managed
-    file: templates/ruby.yml
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/ruby-build@v2.78
 
-  - project: "gitlab-com/gl-infra/common-ci-tasks"
-    ref: v2.77 # renovate:managed
-    file: "danger.yml"
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v2.78
 
 .test_template: &test_definition
   extends: .with_bundle

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.77  # 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.4
-shfmt 3.11.0
-shellcheck 0.10.0
+ruby 3.4.5
+shfmt 3.12
+shellcheck 0.11

data/README.md

@@ -19,10 +19,12 @@ The changelog is available via [**tagged release notes**](https://gitlab.com/git
 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::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_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).
+1. `Labkit::RSpec` for RSpec matchers to test Labkit functionality (requires selective loading). More on the [README](./lib/labkit/rspec/README.md).
 1. `Labkit::Tracing` for handling and propagating distributed traces.
 
 ## Developing

data/config/covered_experiences/schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-06/schema#",
+  "$id": "https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/raw/master/config/covered_experiences/schema.json",
+  "title": "Covered Experience Definition",
+  "description": "Schema for GitLab Covered Experience files",
+  "type": "object",
+  "properties": {
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable description of the covered experience"
+    },
+    "feature_category": {
+      "type": "string",
+      "minLength": 1,
+      "description": "GitLab feature category this experience belongs to"
+    },
+    "urgency": {
+      "type": "string",
+      "enum": [
+        "sync_fast",
+        "sync_slow",
+        "async_fast",
+        "async_slow"
+      ],
+      "description": "Urgency level for this covered experience"
+    }
+  },
+  "required": [
+    "description",
+    "feature_category",
+    "urgency"
+  ]
+}
+

data/config/covered_experiences/testing_sample.yml

@@ -0,0 +1,4 @@
+# yaml-language-server: $schema=./schema.json
+description: "Creating a new merge request in a project"
+feature_category: "source_code_management"
+urgency: "sync_fast"

data/gitlab-labkit.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "grpc", ">= 1.62" # Be sure to update the "grpc-tools" dev_dependency too
   spec.add_runtime_dependency "google-protobuf", "~> 3" # Keep the major version to 3 until we update the `grpc` gem
   spec.add_runtime_dependency "jaeger-client", "~> 1.1.0"
+  spec.add_runtime_dependency 'json-schema', '~> 5.1'
   spec.add_runtime_dependency "opentracing", "~> 0.4"
   spec.add_runtime_dependency "pg_query", ">= 6.1.0", "< 7.0"
   spec.add_runtime_dependency "prometheus-client-mmap", "~> 1.2.9"

data/lib/gitlab-labkit.rb

@@ -7,8 +7,9 @@
 module Labkit
   autoload :System, "labkit/system"
 
-  autoload :Correlation, "labkit/correlation"
   autoload :Context, "labkit/context"
+  autoload :Correlation, "labkit/correlation"
+  autoload :CoveredExperience, "labkit/covered_experience"
   autoload :FIPS, "labkit/fips"
   autoload :Tracing, "labkit/tracing"
   autoload :Logging, "labkit/logging"

data/lib/labkit/context.rb

@@ -5,6 +5,7 @@ require "securerandom"
 require "active_support/core_ext/module/delegation"
 require "active_support/core_ext/string/starts_ends_with"
 require "active_support/core_ext/string/inflections"
+require "active_support/core_ext/object/blank"
 
 module Labkit
   # A context can be used to provide structured information on what resources

data/lib/labkit/covered_experience/README.md

@@ -0,0 +1,185 @@
+# Covered Experience
+
+This module covers the definition for Covered Experiences, as described in the [blueprint](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/covered_experience_slis/#covered-experience-definition).
+
+## Configuration
+
+### Logger Configuration
+
+By default, `Labkit::CoveredExperience` uses `Labkit::Logging::JsonLogger.new($stdout)` for logging. You can configure a custom logger:
+
+```ruby
+Labkit::CoveredExperience.configure do |config|
+  config.logger = Labkit::Logging::JsonLogger.new($stdout)
+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`).
+
+Create a new covered experience file in the registry directory, e.g. config/covered_experiences/merge_request_creation.yaml
+
+The basename of the file will be taken as the covered_experience_id.
+
+The schema header is optional, but if you're using VSCode (or any other editor with support), you can get them validated
+instantaneously in the editor via a [JSON schema plugin](https://marketplace.visualstudio.com/items?itemName=remcohaszing.schemastore).
+
+```yaml
+# yaml-language-server: $schema=https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/raw/master/config/covered_experiences/schema.json
+description: "Creating a new merge request in a project"
+feature_category: "source_code_management"
+urgency: "sync_fast"
+```
+
+**Feature category**
+
+https://docs.gitlab.com/development/feature_categorization/#feature-categorization.
+
+**Urgency**
+
+| Threshold    | Description                                                                                                                                                      | Examples                                                                       | Value |
+|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|-------|
+| `sync_fast`  | A user is awaiting a synchronous response which needs to be returned before they can continue with their action                                                  | A full-page render                                                             | 2s    |
+| `sync_slow`  | A user is awaiting a synchronous response which needs to be returned before they can continue with their action, but which the user may accept a slower response | Displaying a full-text search response while displaying an amusement animation | 5s    |
+| `async_fast` | An async process which may block a user from continuing with their user journey                                                                                  | MR diff update after git push                                                  | 15s   |
+| `async_slow` | An async process which will not block a user and will not be immediately noticed as being slow                                                                   | Notification following an assignment                                           | 5m    |
+
+## Usage
+
+The `Labkit::CoveredExperience` module provides a simple API for measuring and tracking covered experiences in your application.
+
+
+#### Accessing a Covered Experience
+
+```ruby
+# Get a covered experience by ID
+experience = Labkit::CoveredExperience.get('merge_request_creation')
+```
+
+#### Using with a Block (Recommended)
+
+The simplest way to use covered experiences is with a block, which automatically handles starting and completing the experience:
+
+```ruby
+Labkit::CoveredExperience.start('merge_request_creation') do |experience|
+  # Your code here
+  create_merge_request
+
+  # Add checkpoints for important milestones
+  experience.checkpoint
+
+  validate_merge_request
+  experience.checkpoint
+
+  send_notifications
+end
+```
+
+#### Manual Control
+
+For more control, you can manually start, checkpoint, and complete experiences:
+
+```ruby
+experience = Labkit::CoveredExperience.get('merge_request_creation')
+experience.start
+
+# Perform some work
+create_merge_request
+
+# Mark important milestones
+experience.checkpoint
+
+# Perform more work
+validate_merge_request
+experience.checkpoint
+
+# Complete the experience
+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:
+
+```ruby
+Labkit::CoveredExperience.start('merge_request_creation') do |experience|
+  # If this raises an exception, it will be captured automatically
+  risky_operation
+end
+```
+
+For manual control, you can mark errors explicitly:
+
+```ruby
+experience = Labkit::CoveredExperience.get('merge_request_creation')
+experience.start
+
+begin
+  risky_operation
+rescue StandardError => e
+  experience.error!(e)
+  raise
+ensure
+  experience.complete
+end
+```
+
+### Error Behavior
+
+- 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

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+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