gitlab-labkit 1.18.0 → 1.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 154a169d5b47821eb411551dd452755270a671c334b9f041b7c20090b8d35074
-  data.tar.gz: 5373cb3360f29eb1fe9facb99b866423a26785b61c9bc8390f6b4623dba6bff5
+  metadata.gz: cb897d7171414d685d81aa2d55930e9633a46ac6aee0bdca4f36ed34b38e307e
+  data.tar.gz: bd171795616da76cf4262da0f70d6a4e3746bea4e5eab74b3fe554d3597a0c87
 SHA512:
-  metadata.gz: d8393e9574bdeb229a8089dfdcbe90ed1d68bfd9c7a35a95f654800beb18dab5121b48f82c61d71d1d00a83ba6e60e5c595a020bb8e9237b5a636d019645afd0
-  data.tar.gz: 7cf8a3cda6cca43339bf14e814cdd7ee28ebac6de0b4bf21b1c84400eb43bd4061fb0029852fb475293c16a0ae497abc5002556260dd1da680aeb39abc9fbc2c
+  metadata.gz: 4d4174c89606b5949876451b31bdb40a76db573284ed5976afe9806eb33ac592e90d425cb8c3c48412756be9a7db777cfdb00f14649601ff8d0bcc05807bc8c9
+  data.tar.gz: b46236e5b3f59f97cd371f250c397553c32656a51994b556ae43fa4751b2eeb95c5b5bdbc3276d5ad156c861df7f7ff4f39ec93bd3826c854dbfff975fc77602

data/.gitlab-ci.yml

@@ -19,13 +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
-  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/standard-build@v3.23
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/standard-build@v3.24
 
   # Runs rspec tests and rubocop on the project
   # see https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/templates/ruby.md
-  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/ruby-build@v3.23
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/ruby-build@v3.24
 
-  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v3.23
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v3.24
 
 ruby-versions:
   extends: rspec

data/.pre-commit-config.yaml

@@ -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: v3.23  # renovate:managed
+    rev: v3.24  # renovate:managed
 
     hooks:
       - id: shellcheck  # Run shellcheck for changed Shell files

data/lib/labkit/rate_limit/evaluator.rb

@@ -29,6 +29,17 @@ module Labkit
         Result.new(matched: false, error: true, action: :allow)
       end
 
+      # Read-without-increment counterpart to {#check}. Same matching and Result
+      # shape; the underlying Redis counter is not mutated and the TTL is not
+      # extended. A missing Redis key is treated as count=0 (matched, not exceeded).
+      def peek(identifier)
+        peek_rules(identifier)
+      rescue StandardError => e
+        report_error_metrics
+        log_error(e, identifier)
+        Result.new(matched: false, error: true, action: :allow)
+      end
+
       private
 
       def check_rules(identifier)
@@ -44,8 +55,18 @@ module Labkit
         Result.new(matched: false, action: :allow)
       end
 
+      def peek_rules(identifier)
+        @rules.each do |rule|
+          next unless rule_matches?(rule, identifier)
+
+          return peek_rule(rule, identifier)
+        end
+
+        Result.new(matched: false, action: :allow)
+      end
+
       def rule_matches?(rule, identifier)
-        rule.match.all? { |key, value| identifier[key] == value }
+        rule.match.all? { |key, matcher| matcher.match?(identifier[key]) }
       end
 
       def evaluate_rule(rule, identifier)
@@ -54,6 +75,19 @@ module Labkit
         resolved_period = Integer(resolve_value(rule.period))
 
         count, ttl = incr_with_ttl(redis_key, resolved_period)
+        build_result(rule, resolved_limit, resolved_period, count, ttl)
+      end
+
+      def peek_rule(rule, identifier)
+        redis_key = build_redis_key(rule, identifier)
+        resolved_limit = Integer(resolve_value(rule.limit))
+        resolved_period = Integer(resolve_value(rule.period))
+
+        count, ttl = read_with_ttl(redis_key)
+        build_result(rule, resolved_limit, resolved_period, count, ttl)
+      end
+
+      def build_result(rule, resolved_limit, resolved_period, count, ttl)
         exceeded = count > resolved_limit
         action = exceeded ? rule.action : :allow
         info = Result::Info.new(
@@ -108,6 +142,21 @@ module Labkit
         end
       end
 
+      # Pipelined GET + TTL. No EXPIRE: peek must not extend the window.
+      # A missing key (GET => nil, TTL => -2) is reported as count=0; the
+      # build_result fallback then derives reset_at from the rule period
+      # since there is no Redis-side window to read.
+      def read_with_ttl(redis_key)
+        @redis.with do |conn|
+          raw_count, ttl = conn.pipelined do |pipe|
+            pipe.get(redis_key)
+            pipe.ttl(redis_key)
+          end
+          count = raw_count.nil? ? 0 : Integer(raw_count)
+          [count, ttl]
+        end
+      end
+
       def log_error(error, identifier)
         @logger.warn(
           message: "rate_limit_error",

data/lib/labkit/rate_limit/limiter.rb

@@ -38,6 +38,25 @@ module Labkit
         @evaluator.check(id)
       end
 
+      # Read the current rate-limit state without incrementing the counter.
+      # Mirrors {#check} except the underlying counter is not mutated and the
+      # TTL is not extended. Useful for "have we already throttled this caller?"
+      # checks where the caller has another path that does the actual increment
+      # (typical pattern: peek to gate a side-effect, then call #check on the
+      # path that should count).
+      #
+      # When the underlying Redis key does not exist yet, the result reports
+      # count=0, exceeded=false, and remaining=resolved_limit; matched? is
+      # still true because the rule applied. On Redis error the result fails
+      # open identically to {#check}.
+      #
+      # @param identifier [Identifier, Hash] caller attributes for this request
+      # @return [Result]
+      def peek(identifier)
+        id = identifier.is_a?(Identifier) ? identifier : Identifier.new(identifier)
+        @evaluator.peek(id)
+      end
+
       private
 
       def validate_name!(name)

data/lib/labkit/rate_limit/matcher.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Labkit
+  module RateLimit
+    # Matcher is the internal representation of a single key/value predicate in
+    # a Rule#match hash. Rule.new normalizes every match value through
+    # Matcher.build; the Evaluator calls Matcher#match? per identifier value.
+    #
+    # Accepted input shapes (everything else raises ArgumentError):
+    #   - any plain value (String, Symbol, Integer, ...) -> :eq matcher
+    #   - a Regexp instance                              -> :re matcher (Ruby convenience)
+    #   - { eq: <value> }                                -> :eq matcher (canonical, YAML-compatible)
+    #   - { re: <String|Regexp> }                        -> :re matcher (canonical, YAML-compatible)
+    #
+    # Hash-key naming follows the metrics-catalog selector pattern. Glob,
+    # prefix, and other matcher kinds are intentionally out of scope here; see
+    # gitlab-com/gl-infra/production-engineering#28853 for that follow-up.
+    #
+    # An :re matcher coerces the identifier value via #to_s before applying
+    # the regex, so callers can match non-String identifier values such as
+    # Integer status codes (e.g. {status: { re: "^5" }} against status: 503).
+    class Matcher < Data.define(:type, :value)
+      KNOWN_HASH_KEYS = %i[eq re].freeze
+      MAX_REGEX_SOURCE_LENGTH = 200
+      ERROR_INSPECT_LIMIT = 80
+
+      def self.build(input)
+        case input
+        when Regexp
+          new(type: :re, value: input)
+        when Hash
+          from_hash(input)
+        when Array
+          raise ArgumentError,
+            "rate-limit match value must be a single-key Hash like {re: \"...\"} or {eq: ...}, got #{truncate_for_error(input)}"
+        else
+          new(type: :eq, value: input)
+        end
+      end
+
+      def self.from_hash(input)
+        if input.size != 1
+          raise ArgumentError,
+            "rate-limit match value must be a single-key Hash like {re: \"...\"} or {eq: ...}, got #{truncate_for_error(input)}"
+        end
+
+        type, source = input.first
+        type_sym = type.to_sym
+
+        unless KNOWN_HASH_KEYS.include?(type_sym)
+          raise ArgumentError,
+            "rate-limit match value has unknown type key #{truncate_for_error(type)}; accepted: #{KNOWN_HASH_KEYS.inspect}"
+        end
+
+        compile(type_sym, source)
+      end
+      private_class_method :from_hash
+
+      def self.compile(type_sym, source)
+        case type_sym
+        when :eq
+          new(type: :eq, value: source)
+        when :re
+          if source.to_s.length > MAX_REGEX_SOURCE_LENGTH
+            raise ArgumentError,
+              "rate-limit match value {re: ...} source exceeds #{MAX_REGEX_SOURCE_LENGTH} characters"
+          end
+
+          begin
+            new(type: :re, value: Regexp.new(source))
+          rescue RegexpError, TypeError => e
+            raise ArgumentError,
+              "rate-limit match value {re: #{truncate_for_error(source)}} failed to compile: #{e.message}"
+          end
+        end
+      end
+      private_class_method :compile
+
+      def self.truncate_for_error(value)
+        s = value.inspect
+        s.length > ERROR_INSPECT_LIMIT ? "#{s[0, ERROR_INSPECT_LIMIT]}...(truncated)" : s
+      end
+      private_class_method :truncate_for_error
+
+      def match?(identifier_value)
+        case type
+        when :eq
+          value == identifier_value
+        when :re
+          value.match?(identifier_value.to_s)
+        else
+          raise ArgumentError, "unknown matcher type: #{type.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/labkit/rate_limit/rule.rb

@@ -35,7 +35,7 @@ module Labkit
 
         super(
           name: name_str.freeze,
-          match: match.transform_keys(&:to_sym).freeze,
+          match: match.transform_keys(&:to_sym).transform_values { |v| Matcher.build(v) }.freeze,
           limit: limit,
           period: period,
           action: action_sym,

data/lib/labkit/rate_limit.rb

@@ -19,6 +19,7 @@ module Labkit
   module RateLimit
     autoload :Configuration, "labkit/rate_limit/configuration"
     autoload :Identifier, "labkit/rate_limit/identifier"
+    autoload :Matcher, "labkit/rate_limit/matcher"
     autoload :Result, "labkit/rate_limit/result"
     autoload :Rule, "labkit/rate_limit/rule"
     autoload :Evaluator, "labkit/rate_limit/evaluator"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 1.18.0
+  version: 1.19.0
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -603,6 +603,7 @@ files:
 - lib/labkit/rate_limit/evaluator.rb
 - lib/labkit/rate_limit/identifier.rb
 - lib/labkit/rate_limit/limiter.rb
+- lib/labkit/rate_limit/matcher.rb
 - lib/labkit/rate_limit/metrics.rb
 - lib/labkit/rate_limit/result.rb
 - lib/labkit/rate_limit/rule.rb