gitlab-labkit 4.2.0 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1092d43de21613288d5ed802539e0eeab87bee9e8975e223f78aa29116f6cb2d
-  data.tar.gz: 7a4953fd47e09da3cc2f4657cbe563648fec3ea0f0ae63d47e0bf49610b3b39d
+  metadata.gz: f25b6fb5022dbe4d1740df490b991da48f8d2d9432926a0c23ec41dcc566b1c0
+  data.tar.gz: 8e1fb5578809e9a87726e95d181fec9426c67c64aa5862e1ab6afd08d4ac5d20
 SHA512:
-  metadata.gz: 5f885a5454c551e8adc0fd4ad8ca99c81bbc438a61b4787e122fae02f966062d8006c9766cb98f73d2e4c4465a3d5c3a3dd9fe13e44eb76ca21816b1c60571a1
-  data.tar.gz: b11dc29d11ea325ea787af6ad1827bb9963146427d0930c38089b4f1901d21e1faca20437f52cd4a4f8de7b7de85fc0de2932cdcc5f8279c8e9fbe1cd77f711b
+  metadata.gz: dad133ba83a3e8e9b60825936befc9af2586bc80685b227c0517553c32681bd89ac42c0c9c2d7d68b3dd5865e2f54672ca4882711f7b71d92f67442af98abbb7
+  data.tar.gz: d0c781167401e351f2c0989cbdbb2d761886cc5f27b723d96d99228f33bb1a4f04b52af3669c8c655b512378f37842c09d920628abb9284212bf17a1e57d9b9e

data/lib/labkit/rate_limit/README.md

@@ -174,10 +174,17 @@ A `match` hash gates whether a rule applies. Each value is normalised through
 | `Regexp`          | `re`     | `match: { endpoint: %r{\A/api/} }`                     |
 | `{ eq: <value> }` | `eq`     | `match: { method: { eq: "POST" } }` (YAML-friendly)    |
 | `{ re: <source> }`| `re`     | `match: { endpoint: { re: '\A/api/' } }` (YAML-friendly) |
+| `{ oneOf: <Array> }` | `oneOf` | `match: { user: { oneOf: ["7", "42"] } }` (YAML-friendly) |
 
 `re` coerces the identifier value via `#to_s` before matching, so it can be
 used against non-String values (e.g. matching a 503 status against `{ re: '^5' }`).
 
+`oneOf` is set membership via `Set#include?` (`eql?`/`hash` equality, no
+coercion): it agrees with `eq` for Strings, Symbols, booleans, nil, and
+same-class numerics, but cross-type numerics differ (`1 == 1.0`, yet
+`{ oneOf: [1] }` does not match `1.0`). A bare Array is rejected; membership must
+be spelled `{ oneOf: [...] }` explicitly.
+
 Glob and prefix matchers are intentionally out of scope.
 
 ### Evaluation flow

data/lib/labkit/rate_limit/evaluator.rb

@@ -12,6 +12,12 @@ module Labkit
       CHAR_VALUE_MAX_LENGTH = 200
       MISSING_VALUE_SENTINEL = "_unknown_"
 
+      # Carries the rule in flight out of the rule loop and into the rescue in
+      # #check/#peek, where the error is seen but the rule is out of scope.
+      # Per call, not instance state: one Evaluator serves concurrent requests.
+      # Only read while an exception unwinds; nil means no rule was in flight.
+      RuleCursor = Struct.new(:rule)
+
       # Atomic increment-with-TTL Lua script. The whole script runs as one
       # operation from Redis's perspective, so there is no window between
       # the increment and EXPIRE that can leak a key without TTL.
@@ -68,12 +74,13 @@ module Labkit
       end
 
       def check(identifier, cost: 1, rule_context: nil)
-        check_rules(identifier, cost, rule_context)
+        cursor = RuleCursor.new
+        check_rules(identifier, cost, rule_context, cursor)
       rescue StandardError => e
         # Intentionally broad: fail-open applies to any unexpected error (network,
         # timeout, OOM) not only Redis protocol errors.
         report_error_metrics
-        log_error(e, identifier)
+        log_error(e, identifier, cursor.rule)
         Result.error
       end
 
@@ -81,10 +88,11 @@ module Labkit
       # 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, rule_context: nil)
-        peek_rules(identifier, rule_context)
+        cursor = RuleCursor.new
+        peek_rules(identifier, rule_context, cursor)
       rescue StandardError => e
         report_error_metrics
-        log_error(e, identifier)
+        log_error(e, identifier, cursor.rule)
         Result.error
       end
 
@@ -117,11 +125,14 @@ module Labkit
       # counters were incremented. No blocking verdict is lost that way - a
       # :limit rule over its limit returns before any later rule can raise -
       # but a rule declared after the failing one loses its chance to block.
-      # The request is counted and allowed.
-      def check_rules(identifier, cost, rule_context)
+      # The request is counted and allowed. +cursor+ is set before the match, so
+      # a raise from the match itself (e.g. Regexp::TimeoutError) is attributed.
+      def check_rules(identifier, cost, rule_context, cursor)
         result = Result.new
 
         @rules.each do |rule|
+          cursor.rule = rule
+
           next unless rule_matches?(rule, identifier)
 
           if rule.action == :skip
@@ -141,6 +152,9 @@ module Labkit
           return result if result.block?
         end
 
+        # The loop is done, so anything raised from here on belongs to no rule.
+        cursor.rule = nil
+
         report_unmatched_metrics unless result.matched?
         result
       end
@@ -152,10 +166,12 @@ module Labkit
       # peek does not need the count_distinct identifier key - it reads SCARD on
       # the rule-keyed compound key, which contains the cardinality across all
       # members. So missing-key fail-open does not apply here.
-      def peek_rules(identifier, rule_context)
+      def peek_rules(identifier, rule_context, cursor)
         result = Result.new
 
         @rules.each do |rule|
+          cursor.rule = rule
+
           next unless rule_matches?(rule, identifier)
 
           return result.skip!(rule) if rule.action == :skip
@@ -164,6 +180,8 @@ module Labkit
           return result if result.block?
         end
 
+        cursor.rule = nil
+
         result
       end
 
@@ -319,9 +337,14 @@ module Labkit
         end
       end
 
-      def log_error(error, identifier)
+      # rule is nil when the error was raised with no rule in flight - before the
+      # loop reached one, or after it finished - so the field is logged as null
+      # rather than omitted, the same way identifier is. A named rule is the rule
+      # whose match or evaluation raised.
+      def log_error(error, identifier, rule = nil)
         @logger.warn(
           name: @name,
+          rule: rule&.name,
           Labkit::Fields::ERROR_TYPE => "rate_limit_error",
           Labkit::Fields::CLASS_NAME => error.class.to_s,
           Labkit::Fields::ERROR_MESSAGE => error.message,

data/lib/labkit/rate_limit/matcher.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Labkit
   module RateLimit
     # Matcher is the internal representation of a single key/value predicate in
@@ -11,6 +13,14 @@ module Labkit
     #   - a Regexp instance                              -> :re matcher (Ruby convenience)
     #   - { eq: <value> }                                -> :eq matcher (canonical, YAML-compatible)
     #   - { re: <String|Regexp> }                        -> :re matcher (canonical, YAML-compatible)
+    #   - { oneOf: <Array> }                             -> :oneOf matcher (set membership, YAML-compatible)
+    #
+    # A bare Array is rejected rather than treated as :oneOf, so a value that
+    # was meant as a single matcher hash but arrived as an Array fails loudly
+    # instead of silently becoming a membership test.
+    #
+    # :oneOf membership is Set#include? (eql?/hash equality), not :eq's ==, so
+    # cross-type numerics differ (1 == 1.0, but {oneOf: [1]} does not match 1.0).
     #
     # Hash-key naming follows the metrics-catalog selector pattern. Glob,
     # prefix, and other matcher kinds are intentionally out of scope here; see
@@ -20,7 +30,7 @@ module Labkit
     # 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
+      KNOWN_HASH_KEYS = %i[eq re oneOf].freeze
       MAX_REGEX_SOURCE_LENGTH = 200
       ERROR_INSPECT_LIMIT = 80
 
@@ -42,18 +52,14 @@ module Labkit
         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)}"
+          raise ArgumentError, invalid_shape_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
+        raise ArgumentError, invalid_shape_error(input) if input.size != 1
 
         type, source = input.first
         type_sym = type.to_sym
@@ -71,6 +77,13 @@ module Labkit
         case type_sym
         when :eq
           new(type: :eq, value: source)
+        when :oneOf
+          unless source.is_a?(Array)
+            raise ArgumentError,
+              "rate-limit match value {oneOf: ...} must be an Array, got #{truncate_for_error(source)}"
+          end
+
+          new(type: :oneOf, value: Set.new(source).freeze)
         when :re
           if source.to_s.length > MAX_REGEX_SOURCE_LENGTH
             raise ArgumentError,
@@ -113,6 +126,12 @@ module Labkit
 
       private_class_method :with_match_timeout
 
+      def self.invalid_shape_error(input)
+        "rate-limit match value must be a single-key Hash like {re: \"...\"}, {eq: ...} or {oneOf: [...]}, " \
+          "got #{truncate_for_error(input)}"
+      end
+      private_class_method :invalid_shape_error
+
       def self.truncate_for_error(value)
         s = value.inspect
         s.length > ERROR_INSPECT_LIMIT ? "#{s[0, ERROR_INSPECT_LIMIT]}...(truncated)" : s
@@ -123,6 +142,8 @@ module Labkit
         case type
         when :eq
           value == identifier_value
+        when :oneOf
+          value.include?(identifier_value)
         when :re
           value.match?(identifier_value.to_s)
         else

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 4.4.0
 platform: ruby
 authors:
 - Andrew Newdigate