gitlab-labkit 1.17.0 → 1.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7177b8f9210f24958a14c92f17ad35cc8d4ad7732e04a9407569e865ef2bf364
-  data.tar.gz: 688c6dd7b7c1a8c1062a1e17c534fa833f86053aff8945ab4d296c2223784711
+  metadata.gz: cb897d7171414d685d81aa2d55930e9633a46ac6aee0bdca4f36ed34b38e307e
+  data.tar.gz: bd171795616da76cf4262da0f70d6a4e3746bea4e5eab74b3fe554d3597a0c87
 SHA512:
-  metadata.gz: 2b54fe16d5c1cfe12c704a4e84cdea8dece8155dcaa04132c9e52442bec03e6338f6a4bcb065aa87931aa2fedcbd2ecb5ecec390b00d110267ee54e95a5c694c
-  data.tar.gz: 8abc6a48c3f1b138a84f8502e5c4300bec5f05f98b0c8defb4280d12b1d424f70cf64e0afe3cc344ce61ceae145e9aaf11f252d9611da1e5c6a1f25aa37fe867
+  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)
@@ -53,14 +74,30 @@ module Labkit
         resolved_limit = Integer(resolve_value(rule.limit))
         resolved_period = Integer(resolve_value(rule.period))
 
-        count = incr_with_ttl(redis_key, resolved_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
-
-        Result.new(
-          matched: true, exceeded: exceeded, action: action, rule: rule,
-          resolved_limit: resolved_limit, resolved_period: resolved_period
+        info = Result::Info.new(
+          resolved_limit: resolved_limit, resolved_period: resolved_period,
+          count: count,
+          remaining: [resolved_limit - count, 0].max,
+          reset_at: Time.now.utc + (ttl >= 0 ? ttl : resolved_period)
         )
+
+        Result.new(matched: true, exceeded: exceeded, action: action, rule: rule, info: info)
       end
 
       def build_redis_key(rule, identifier)
@@ -91,12 +128,32 @@ module Labkit
         end
       end
 
+      # Pipelines INCR and TTL so both are fetched in a single round-trip.
+      # EXPIRE follows as a separate call only on first write (count == 1).
+      # On first write TTL will be -1 (expiry not yet set); callers fall back to period.
       def incr_with_ttl(redis_key, period)
         @redis.with do |conn|
-          count = conn.incr(redis_key)
-          # Set expiry only on first write to avoid resetting TTL on each call
+          count, ttl = conn.pipelined do |pipe|
+            pipe.incr(redis_key)
+            pipe.ttl(redis_key)
+          end
           conn.expire(redis_key, period) if count == 1
-          count
+          [count, ttl]
+        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
 
@@ -117,11 +174,11 @@ module Labkit
         )
         Metrics.limit_gauge.set(
           { rate_limiter: @name, rule: result.rule.name },
-          result.resolved_limit
+          result.info.resolved_limit
         )
         Metrics.period_gauge.set(
           { rate_limiter: @name, rule: result.rule.name },
-          result.resolved_period
+          result.info.resolved_period
         )
       end
 

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/result.rb

@@ -3,22 +3,19 @@
 module Labkit
   module RateLimit
     # Result is the return value of Limiter#check.
-    # matched?         - true if a rule's match conditions were satisfied
-    # exceeded?        - true if the matched rule's counter exceeded its limit
-    # 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
-    #                             no rule matched, or error (fail-open)
-    #                    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)
-    # resolved_limit   - the resolved limit value as Integer (nil when matched? is false or error)
-    # resolved_period  - the resolved period value as Integer (nil when matched? is false or error)
-    Result = Data.define(:matched, :exceeded, :action, :rule, :error, :resolved_limit, :resolved_period) do
-      def initialize(
-        matched:, action:, exceeded: false, rule: nil, error: false,
-        resolved_limit: nil, resolved_period: nil)
+    # matched?  - true if a rule's match conditions were satisfied
+    # exceeded? - true if the matched rule's counter exceeded its limit
+    # 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
+    #                      no rule matched, or error (fail-open)
+    #             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?
+    Result = Data.define(:matched, :exceeded, :action, :rule, :error, :info) do
+      def initialize(matched:, action: nil, exceeded: false, rule: nil, error: false, info: nil)
         super
       end
 
@@ -33,6 +30,27 @@ module Labkit
       def error?
         error
       end
+
+      # Returns RFC-compliant rate limit response headers, or {} when no rule matched or an error occurred.
+      # Keys: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (Unix timestamp).
+      # reset_at is advisory only - derived from a pipelined redis.ttl call, not fully atomic.
+      def to_response_headers
+        return {} unless matched? && !error? && info
+
+        {
+          "RateLimit-Limit" => info.resolved_limit.to_s,
+          "RateLimit-Remaining" => info.remaining.to_s,
+          "RateLimit-Reset" => info.reset_at.to_i.to_s
+        }
+      end
     end
+
+    # Per-window counter data attached to a matched Result.
+    # resolved_limit  - the evaluated limit Integer for this rule
+    # resolved_period - the evaluated period Integer (seconds) for this rule
+    # count           - the raw INCR value; useful for utilization-ratio metrics
+    # remaining       - requests remaining before the limit is hit (floors at 0)
+    # reset_at        - best-effort UTC Time when the counter window resets
+    Result::Info = Data.define(:resolved_limit, :resolved_period, :count, :remaining, :reset_at)
   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.17.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