gitlab-labkit 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fcf883261bb809a67748d4f15c2a520ae392d3d069b5852cc20abf56e428b4e
-  data.tar.gz: ce56f2ec2b2dce0b420d0096ea6b4a48b54a91c350b802a245dcc0cae9219908
+  metadata.gz: ed4c330d977763fb6063a9caab83352d59f32c46ac10a097f33f468cb06b2ddc
+  data.tar.gz: 558fae5ff6684b13cce03ee9b5f306c949a19c1a44b89c3fcae0567caa8175cc
 SHA512:
-  metadata.gz: 70d57193fc2778250b004df0e39f7f98ff6f1bc5356d601f664b632cd6a7e9b4f2f772b6251406702b5cea84bda6fed02ad29d1ca196f2b29462e4887ded4b6e
-  data.tar.gz: 1cd77a020fe80b311512acf08b433913f0e9a06edce05a10961c018c19a1270c9420b477731cb88d4ceb5b641ee0a6d0ad4c34fc1bee528d2febae1f83a521dd
+  metadata.gz: f1cd4013a210766f17a988f7922e900b9b00f74089fdde68e143cc718da629bd5d7442248ee47d15d0d7aa513e85eae6d9d642a5ddbfa5eddbe74046f7674cbb
+  data.tar.gz: 22dae3a5fb187c7118f4dd86df667982c1e72ef023d5a52aad1c6c10813845f3128d714973957c3ddca2b436b1419115904ca5bd76510315f57a7a8d3cd48078

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

@@ -25,7 +25,8 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "grpc", ">= 1.75" # Be sure to update the "grpc-tools" dev_dependency too
   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"

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.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -98,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: '5.1'
+        version: 2.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.1'
+        version: 2.4.0
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.2
 - !ruby/object:Gem::Dependency
   name: opentracing
   requirement: !ruby/object:Gem::Requirement
@@ -468,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