gitlab-labkit 1.18.0 → 1.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 154a169d5b47821eb411551dd452755270a671c334b9f041b7c20090b8d35074
-  data.tar.gz: 5373cb3360f29eb1fe9facb99b866423a26785b61c9bc8390f6b4623dba6bff5
+  metadata.gz: f5f66c856712fe4736592757a1dab3a95aa920359ed0bbca72a638d0983df164
+  data.tar.gz: 89f0452f48f07968f29b3890fb7f71b1aac42b5f4b6e7cdcad556a0c3f548d6f
 SHA512:
-  metadata.gz: d8393e9574bdeb229a8089dfdcbe90ed1d68bfd9c7a35a95f654800beb18dab5121b48f82c61d71d1d00a83ba6e60e5c595a020bb8e9237b5a636d019645afd0
-  data.tar.gz: 7cf8a3cda6cca43339bf14e814cdd7ee28ebac6de0b4bf21b1c84400eb43bd4061fb0029852fb475293c16a0ae497abc5002556260dd1da680aeb39abc9fbc2c
+  metadata.gz: 1a9bf8af827028ae5e68857650cdf2af5e6c49c16360e123a1f653c0e38530ba89a4f1a5179ee50d540dc4f71a1fd766f93517d622d1a25d72d39be5e545b0b1
+  data.tar.gz: 58da58ed8eae9c02437fd0a3f41a529e36feeade438d9dcee63d4448165a95b4d1b3d100c1e27384aa5763a002fbcf9eccc33cb283258e8baafbfbc9366bc56b

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,23 +29,49 @@ 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
 
+      # :log rules are non-terminating: they emit metrics and continue,
+      # so a shadow :log rule cannot disable a following :block rule.
       def check_rules(identifier)
         @rules.each do |rule|
           next unless rule_matches?(rule, identifier)
 
           result = evaluate_rule(rule, identifier)
           report_matched_metrics(result)
-          return result
+          return result unless rule.action == :log
         end
 
         report_unmatched_metrics
         Result.new(matched: false, action: :allow)
       end
 
+      # Mirror of check_rules without metrics: peek skips :log rules (their state
+      # is unobservable through peek).
+      def peek_rules(identifier)
+        @rules.each do |rule|
+          next if rule.action == :log
+          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 +80,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 +147,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/metrics.rb

@@ -5,6 +5,9 @@ module Labkit
     module Metrics
       module_function
 
+      # :log rules are non-terminating: a check that matched only :log rules
+      # increments calls_total once per matched :log rule AND once with
+      # rule="unmatched", action="allow", since no terminating decision was made.
       def calls_total
         Labkit::Metrics::Client.counter(
           :gitlab_labkit_rate_limiter_calls_total,

data/lib/labkit/rate_limit/result.rb

@@ -8,9 +8,9 @@ module Labkit
     # action    - the outcome: what the caller should do
     #             :block = rule matched, exceeded, rule configured to block
     #             :log   = rule matched, exceeded, rule configured to log only
-    #             :allow = rule matched but count within limit, or
+    #             :allow = rule matched but count within limit, rule configured to allow,
     #                      no rule matched, or error (fail-open)
-    #             The rule's configured action is available via rule.action
+    #             The rule's configured action is available via rule.action.
     # rule      - the matched Rule object (nil when matched? is false)
     # error?    - true if Redis was unavailable; result fails open (exceeded? is false)
     # info      - Result::Info with per-window counters; nil when matched? is false or error?

data/lib/labkit/rate_limit/rule.rb

@@ -2,7 +2,7 @@
 
 module Labkit
   module RateLimit
-    KNOWN_ACTIONS = [:block, :log].freeze
+    KNOWN_ACTIONS = %i[block log allow].freeze
     RULE_NAME_PATTERN = /\A[a-z0-9_]+\z/
     RULE_NAME_MAX_LENGTH = 64
 
@@ -12,7 +12,9 @@ module Labkit
     #                   the rule to apply; empty hash matches any identifier
     # limit           - request threshold; may be a callable (resolved per check)
     # period          - window in seconds; may be a callable (resolved per check)
-    # action          - :block (enforce) or :log (count and log, but do not block)
+    # action          - :block (enforce), :log (count and log only, do not block,
+    #                   evaluation continues to subsequent rules), or :allow
+    #                   (bypass: short-circuit evaluation with no Redis writes)
     # characteristics - identifier keys used to build the compound Redis counter key
     #
     # +name+ must be a lowercase alphanumeric-and-underscore string of at most 64
@@ -35,7 +37,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.20.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