gitlab-labkit 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 848c7a3b2a208349e041ead5190bb2f665190100e9c4868b3391f040674834b7
-  data.tar.gz: be220cf29fa57499b1101cabda163816fd37f77b09b5b3be93464cd87c6294b6
+  metadata.gz: ed4c330d977763fb6063a9caab83352d59f32c46ac10a097f33f468cb06b2ddc
+  data.tar.gz: 558fae5ff6684b13cce03ee9b5f306c949a19c1a44b89c3fcae0567caa8175cc
 SHA512:
-  metadata.gz: e5e4181d842aa238bc113b4d1486471f71b44e3d04d7f8613583e2ae23eeb33a4c6e275a5fccb18b2db5a962c0e4ff294b2df7a6eb9bd6c08a8aaf88a9146a96
-  data.tar.gz: eeab7e40652242988f381b9192a9384a9098a7bd31ad8ef6e8f0b17c5c6f17032a8f2199f9b1fbe543e9d11ba04a30cb5c59a2b96d9bb86df3a30a026924e96f
+  metadata.gz: f1cd4013a210766f17a988f7922e900b9b00f74089fdde68e143cc718da629bd5d7442248ee47d15d0d7aa513e85eae6d9d642a5ddbfa5eddbe74046f7674cbb
+  data.tar.gz: 22dae3a5fb187c7118f4dd86df667982c1e72ef023d5a52aad1c6c10813845f3128d714973957c3ddca2b436b1419115904ca5bd76510315f57a7a8d3cd48078

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-05-05 15:54:30 UTC using RuboCop version 1.68.0.
+# on 2025-11-17 07:59:08 UTC using RuboCop version 1.71.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -25,7 +25,7 @@ Fips/SHA1:
   Exclude:
     - 'spec/labkit/fips_spec.rb'
 
-# Offense count: 8
+# Offense count: 10
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Include.
 # Include: **/*.gemspec
@@ -56,11 +56,26 @@ Layout/ClassStructure:
   Exclude:
     - 'lib/labkit/tracing/rack_middleware.rb'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 Layout/EmptyLineAfterMagicComment:
   Exclude:
     - 'lib/labkit/logging/json_logger.rb'
+    - 'spec/support/grpc_service/test_pb.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/EmptyLines:
+  Exclude:
+    - 'spec/support/grpc_service/test_pb.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: empty_lines, empty_lines_except_namespace, empty_lines_special, no_empty_lines, beginning_only, ending_only
+Layout/EmptyLinesAroundClassBody:
+  Exclude:
+    - 'spec/support/grpc_service/test_services_pb.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
@@ -144,7 +159,8 @@ Lint/UnexpectedBlockArity:
 
 # Offense count: 41
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AutoCorrect, AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods.
+# Configuration parameters: AutoCorrect, AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
+# NotImplementedExceptions: NotImplementedError
 Lint/UnusedMethodArgument:
   Exclude:
     - 'lib/labkit/correlation/grpc/client_interceptor.rb'
@@ -254,7 +270,7 @@ RSpec/LetBeforeExamples:
   Exclude:
     - 'spec/labkit/tracing_spec.rb'
 
-# Offense count: 20
+# Offense count: 31
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 8
@@ -326,7 +342,7 @@ Rails/NegateInclude:
   Exclude:
     - 'spec/labkit/correlation/grpc/client_interceptor_spec.rb'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports unsafe autocorrection (--autocorrect-all).
 # Configuration parameters: Include.
 # Include: **/Rakefile, **/*.rake
@@ -361,6 +377,14 @@ Style/AsciiComments:
   Exclude:
     - 'spec/support/grpc_service/test_service_impl.rb'
 
+# Offense count: 7
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: allow_single_line, allow_always, disallow
+Style/EndlessMethod:
+  Exclude:
+    - 'lib/labkit/user_experience_sli/null.rb'
+
 # Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowedVars.
@@ -369,6 +393,15 @@ Style/FetchEnvVar:
     - 'lib/labkit/tracing.rb'
     - 'spec/helpers/stub_env.rb'
 
+# Offense count: 5
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/FileNull:
+  Exclude:
+    - 'spec/labkit/logging/json_logger_spec.rb'
+    - 'spec/labkit/middleware/sidekiq/user_experience_sli/client_spec.rb'
+    - 'spec/labkit/middleware/sidekiq/user_experience_sli/server_spec.rb'
+    - 'spec/spec_helper.rb'
+
 # Offense count: 8
 # This cop supports unsafe autocorrection (--autocorrect-all).
 # Configuration parameters: EnforcedStyle.
@@ -381,7 +414,7 @@ Style/FrozenStringLiteralComment:
     - 'spec/labkit/tracing/rails/active_support/cache_generate_instrumenter_spec.rb'
     - 'spec/labkit/tracing/rails/active_support/cache_read_instrumenter_spec.rb'
     - 'spec/labkit/tracing/rails/active_support/cache_write_instrumenter_spec.rb'
-    - 'spec/support/grpc_service/test_pb.rb'
+    - 'spec/support/grpc_service/test_services_pb.rb'
     - 'tools/update-changelog.rb'
 
 # Offense count: 2
@@ -397,7 +430,7 @@ Style/GuardClause:
   Exclude:
     - 'lib/labkit/logging/json_logger.rb'
 
-# Offense count: 34
+# Offense count: 33
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, EnforcedShorthandSyntax, UseHashRocketsWithSymbolValues, PreferHashRocketsForNonAlnumEndingSymbols.
 # SupportedStyles: ruby19, hash_rockets, no_mixed_keys, ruby19_no_mixed_keys
@@ -408,7 +441,6 @@ Style/HashSyntax:
     - 'lib/labkit/tracing/tracing_utils.rb'
     - 'spec/labkit/tracing/rack_middleware_spec.rb'
     - 'spec/labkit/tracing/redis/redis_interceptor_helper_spec.rb'
-    - 'spec/support/grpc_service/test_pb.rb'
     - 'spec/support/tracing/shared_examples.rb'
 
 # Offense count: 1
@@ -459,11 +491,12 @@ Style/RedundantBegin:
   Exclude:
     - 'spec/labkit/net_http_publisher_spec.rb'
 
-# Offense count: 3
+# Offense count: 4
 # This cop supports safe autocorrection (--autocorrect).
 Style/RedundantConstantBase:
   Exclude:
     - 'spec/labkit/logging/grpc/server_interceptor_spec.rb'
+    - 'spec/support/grpc_service/test_pb.rb'
 
 # Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
@@ -491,6 +524,12 @@ Style/RedundantReturn:
   Exclude:
     - 'lib/labkit/tracing/jaeger_factory.rb'
 
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantStringEscape:
+  Exclude:
+    - 'spec/support/grpc_service/test_pb.rb'
+
 # Offense count: 3
 # This cop supports unsafe autocorrection (--autocorrect-all).
 # Configuration parameters: Mode.
@@ -519,7 +558,7 @@ Style/SymbolLiteral:
     - 'lib/labkit/tracing/tracing_utils.rb'
     - 'spec/support/tracing/shared_examples.rb'
 
-# Offense count: 39
+# Offense count: 42
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleForMultiline.
 # SupportedStylesForMultiline: comma, consistent_comma, no_comma
@@ -545,16 +584,16 @@ Style/TrailingCommaInArrayLiteral:
     - 'spec/labkit/tracing/rails/active_support/cache_generate_instrumenter_spec.rb'
     - 'spec/labkit/tracing/rails/active_support/cache_write_instrumenter_spec.rb'
 
-# Offense count: 84
+# Offense count: 85
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleForMultiline.
 # SupportedStylesForMultiline: comma, consistent_comma, no_comma
 Style/TrailingCommaInHashLiteral:
   Enabled: false
 
-# Offense count: 68
+# Offense count: 75
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns.
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
-  Max: 294
+  Max: 567

data/Rakefile

@@ -18,7 +18,13 @@ end
 desc "Generate test protobuf stubs"
 task :gen_test_proto do
   system "grpc_tools_ruby_protoc --ruby_out=. --grpc_out=. spec/support/grpc_service/test.proto"
-  Rufo::Command.run(["spec/support/grpc_service/test_pb.rb", "spec/support/grpc_service/test_services_pb.rb"])
+
+  # Fix require statement to use require_relative for test environment.
+  # This is a workaround for https://github.com/grpc/grpc/issues/29027.
+  services_file = "spec/support/grpc_service/test_services_pb.rb"
+  content = File.read(services_file)
+  content.gsub!(%r{^require ['"]spec/support/grpc_service/test_pb['"]$}, "require_relative 'test_pb'")
+  File.write(services_file, content)
 end
 
 task :fix => ["rubocop:autocorrect"]

data/config/user_experience_slis/schema.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "http://json-schema.org/draft-06/schema#",
+  "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/raw/master/config/user_experience_slis/schema.json",
   "title": "User Experience SLI Definition",
   "description": "Schema for GitLab User Experience SLI files",
@@ -12,8 +12,8 @@
     },
     "feature_category": {
       "type": "string",
-      "minLength": 1,
-      "description": "GitLab feature category this experience belongs to"
+      "description": "GitLab feature category this experience belongs to",
+      "$ref": "https://gitlab.com/gitlab-org/gitlab/-/raw/master/config/feature_categories/schema.json"
     },
     "urgency": {
       "type": "string",

data/gitlab-labkit.gemspec

@@ -23,9 +23,10 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "actionpack", ">= 5.0.0", "< 8.1.0"
   spec.add_runtime_dependency "activesupport", ">= 5.0.0", "< 8.1.0"
   spec.add_runtime_dependency "grpc", ">= 1.75" # 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 "google-protobuf", ">= 3.25", "< 5.0"
   spec.add_runtime_dependency "jaeger-client", "~> 1.1.0"
-  spec.add_runtime_dependency 'json-schema', '~> 5.1'
+  spec.add_runtime_dependency 'json_schemer', '~> 2.4.0'
+  spec.add_runtime_dependency "openssl", "~> 3.3.2"
   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"
@@ -35,7 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "excon", "~> 0.78.1"
   spec.add_development_dependency "faraday", "~> 1.10.3"
   spec.add_development_dependency "gitlab-dangerfiles", "~> 2.11.0"
-  spec.add_development_dependency "gitlab-styles", "~> 13.0.2"
+  spec.add_development_dependency "gitlab-styles", "~> 13.1"
   spec.add_development_dependency "grpc-tools", ">= 1.75"
   spec.add_development_dependency "httparty", "~> 0.22.0"
   spec.add_development_dependency "httpclient", "~> 2.9.0"

data/lib/labkit/json_schema/README.md

@@ -0,0 +1,74 @@
+# JSON Schema Reference Resolver
+
+## Overview
+
+The `RefResolver` class provides HTTP/HTTPS-based resolution for external JSON schema references. It enables validation of JSON data against schemas that reference remote schema definitions, with built-in caching and timeout protection.
+
+## Why Use RefResolver?
+
+When working with JSON schemas, you may encounter `$ref` properties that point to external schema definitions hosted remotely:
+
+```json
+{
+  "$ref": "https://example.com/schemas/common.json#/definitions/address"
+}
+```
+
+The `RefResolver` solves several key challenges:
+
+- **Remote Schema Resolution**: Automatically fetches and parses external schema definitions over HTTP/HTTPS
+- **Performance Optimization**: Caches fetched schemas to avoid redundant network requests
+- **Reliability**: Implements configurable timeouts to prevent hanging on slow or unresponsive endpoints
+- **Error Handling**: Provides clear error messages for network failures, timeouts, and invalid JSON responses
+
+## How to Use
+
+### Basic Usage
+
+The `RefResolver` is designed to work with the [JSONSchemer](https://github.com/davishmcclurg/json_schemer) gem:
+
+```ruby
+require 'labkit/json_schema/ref_resolver'
+
+# Create a resolver instance
+resolver = Labkit::JsonSchema::RefResolver.new
+
+# Use with JSONSchemer
+schema = JSONSchemer.schema(
+  your_schema_hash,
+  ref_resolver: resolver
+)
+
+# Validate data
+schema.valid?(your_data)
+```
+
+### Custom Timeout Configuration
+
+By default, the resolver uses a 2-second timeout for both connection and read operations. You can customize this:
+
+```ruby
+# Use a 5-second timeout
+resolver = Labkit::JsonSchema::RefResolver.new(timeout_s: 5)
+```
+
+### Cache Management
+
+The resolver maintains a class-level cache to share fetched schemas across instances:
+
+```ruby
+# Access the cache
+Labkit::JsonSchema::RefResolver.cache
+
+# Clear the cache if needed
+Labkit::JsonSchema::RefResolver.cache.clear
+```
+
+## Use Case Example
+
+The `RefResolver` is used in the User Experience SLI Registry [lib/labkit/user_experience_sli/registry.rb](lib/labkit/user_experience_sli/registry.rb) to validate user experience definitions against a JSON schema.
+
+## Implementation Details
+
+- Only HTTP and HTTPS schemes are supported. Other schemes (FTP, file://, etc.) will raise an error.
+- The class-level cache is shared across all instances. In multi-threaded environments, consider using appropriate synchronization mechanisms if cache consistency is critical.

data/lib/labkit/json_schema/ref_resolver.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Labkit
+  module JsonSchema
+    # This class resolves JSON schema references (e.g., "$ref": "http://example.com/schema.json")
+    # by fetching remote schemas over HTTP/HTTPS and caching them.
+    # It is used by JSONSchemer to resolve external schema definitions.
+    # We need it to validate JSON data against schemas that might be hosted remotely.
+    class RefResolver
+      mattr_accessor :cache, default: {}
+
+      def initialize(timeout_s: 2)
+        @timeout_s = timeout_s
+      end
+
+      def call(uri)
+        uri_str = uri.to_s
+
+        return cache[uri_str] if cache.key?(uri_str)
+
+        cache[uri_str] = fetch_remote_schema(uri_str)
+      end
+
+      private
+
+      def fetch_remote_schema(uri_str)
+        uri = URI(uri_str)
+
+        raise(JSONSchemer::UnknownRef, "Unsupported URI scheme: #{uri_str}") unless %w[http https].include?(uri.scheme)
+
+        response = Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == 'https',
+          open_timeout: @timeout_s,
+          read_timeout: @timeout_s
+        ) do |http|
+          request = Net::HTTP::Get.new(uri.request_uri)
+          http.request(request)
+        end
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise(
+            JSONSchemer::UnknownRef,
+            "Failed to fetch #{uri_str}: #{response.code} #{response.message}"
+          )
+        end
+
+        JSON.parse(response.body)
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise(JSONSchemer::UnknownRef, "Timeout fetching #{uri_str}: #{e.message}")
+      rescue JSON::ParserError => e
+        raise(JSONSchemer::UnknownRef, "Invalid JSON at #{uri_str}: #{e.message}")
+      rescue SocketError, Errno::ECONNREFUSED => e
+        raise(JSONSchemer::UnknownRef, "Connection failed for #{uri_str}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/labkit/user_experience_sli/README.md

@@ -33,6 +33,23 @@ This allows you to:
 
 **Note:** The registry is automatically reset when the configuration changes, so the new path takes effect immediately.
 
+### RefResolver Timeout Configuration
+
+When validating user experience SLI definitions against JSON schemas, the system may need to fetch remote schema references over HTTP/HTTPS. By default, the timeout for these requests is 2 seconds. You can configure a custom timeout:
+
+```ruby
+Labkit::UserExperienceSli.configure do |config|
+  config.ref_resolver_timeout = 5  # Set timeout to 5 seconds
+end
+```
+
+This configuration is useful when:
+- Working in environments with slower network connections
+- Fetching schemas from remote servers with higher latency
+- Needing stricter timeout constraints for faster failure detection
+
+**Note:** The timeout applies to both connection opening and reading operations when fetching remote JSON schema references.
+
 ### User Experience Definitions
 
 User Experience SLI definitions will be lazy loaded from the default directory (`config/user_experience_slis`).

data/lib/labkit/user_experience_sli/registry.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 require 'forwardable'
-require 'json-schema'
+require 'json_schemer'
 require 'pathname'
 require 'yaml'
+require 'labkit/json_schema/ref_resolver'
 
 module Labkit
   module UserExperienceSli
@@ -77,8 +78,7 @@ module Labkit
         content = YAML.safe_load(file_path.read)
         return nil unless content.is_a?(Hash)
 
-        errors = JSON::Validator.fully_validate(schema, content)
-        return Definition.new(user_experience_id: experience_id, **content) if errors.empty?
+        return Definition.new(user_experience_id: experience_id, **content) if schema.valid?(content)
 
         warn("Invalid schema for #{file_path}")
 
@@ -90,7 +90,11 @@ module Labkit
       end
 
       def schema
-        @schema ||= JSON.parse(File.read(SCHEMA_PATH))
+        @schema ||= begin
+          schema = JSON.parse(File.read(SCHEMA_PATH))
+          timeout = Labkit::UserExperienceSli.configuration.ref_resolver_timeout
+          JSONSchemer.schema(schema, ref_resolver: Labkit::JsonSchema::RefResolver.new(timeout_s: timeout))
+        end
       end
 
       def warn(message)

data/lib/labkit/user_experience_sli.rb

@@ -16,11 +16,12 @@ module Labkit
   module UserExperienceSli
     # Configuration class for UserExperienceSli
     class Configuration
-      attr_accessor :logger, :registry_path
+      attr_accessor :logger, :registry_path, :ref_resolver_timeout
 
       def initialize
         @logger = Labkit::Logging::JsonLogger.new($stdout)
         @registry_path = File.join("config", "user_experience_slis")
+        @ref_resolver_timeout = 2
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -67,16 +67,22 @@ dependencies:
   name: google-protobuf
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '3.25'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.25'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: jaeger-client
   requirement: !ruby/object:Gem::Requirement
@@ -92,19 +98,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 1.1.0
 - !ruby/object:Gem::Dependency
-  name: json-schema
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+- !ruby/object:Gem::Dependency
+  name: openssl
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.1'
+        version: 3.3.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.1'
+        version: 3.3.2
 - !ruby/object:Gem::Dependency
   name: opentracing
   requirement: !ruby/object:Gem::Requirement
@@ -221,14 +241,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 13.0.2
+        version: '13.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 13.0.2
+        version: '13.1'
 - !ruby/object:Gem::Dependency
   name: grpc-tools
   requirement: !ruby/object:Gem::Requirement
@@ -462,6 +482,8 @@ files:
 - lib/labkit/fields.rb
 - lib/labkit/fips.rb
 - lib/labkit/httpclient_publisher.rb
+- lib/labkit/json_schema/README.md
+- lib/labkit/json_schema/ref_resolver.rb
 - lib/labkit/logging.rb
 - lib/labkit/logging/grpc.rb
 - lib/labkit/logging/grpc/server_interceptor.rb