gitlab-labkit 5.2.1 → 5.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a73e80c74e6f2578a9a86a5ad9c76c3c3c9ff4afc8c1deea262408763e84588
-  data.tar.gz: e7e1d625f3c634a04fd9a6aea0036270966c3b3a6e924edfebfd56713ede00ef
+  metadata.gz: aed1a8c61c569399190d8729a7121c1f45a5d4cd9d95f0f94cb83712f369d4c5
+  data.tar.gz: 7c20c5fe22b0012fd0149d238b525254d18a97da8df75e2bdf7c83da5f25796f
 SHA512:
-  metadata.gz: 77d32a2075415b452d10b1b01a4ef3679d46bbaacd1bef798ce2b17b0b0109a9ec26565f8065600df41f1090752ae311b5a90fadfd434b4e39025d57dcf2f46f
-  data.tar.gz: c8e099df23ea1312476d3d1301044f5de159b6ed25098d755b47df2b7653b8958a9f30c778d5742620c4d804255ac31250f7834e090981803e54d26f4ab6f67b
+  metadata.gz: 33023dcf68427b86e1c63440e7edc0795a1cd612dea306e025170ad3a070cd394622e69d2b9f8b44dcae63674a3f70bf4715b5e2c0e1dd19cb5fdc884a0c7137
+  data.tar.gz: dd800774b482b0b51c79640d1b97080ce5688fb30e2c06b6b0542606a1e7b08ec719a17c4b0111cc39f697c9582bc4abe790a8f94f94942cdfd5d0e630dc410c

data/.gitlab-ci.yml

@@ -79,6 +79,13 @@ conformance-spec:
   variables:
     LABKIT_RUBY_SHA: $CI_COMMIT_SHA
   rules:
+    # Renovate's project-token bot cannot create pipelines in labkit-spec
+    # (GitLab forbids project bots from joining other projects), so its MRs
+    # would hard-fail the bridge. Attempt the trigger but do not block; a
+    # human re-running the pipeline gates the MR properly (it runs as them).
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $GITLAB_USER_LOGIN =~ /^project_\d+_bot/'
+      changes: !reference [.conformance-trigger-paths, changes]
+      allow_failure: true
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
       changes: !reference [.conformance-trigger-paths, changes]
   trigger:

data/AGENTS.md

@@ -0,0 +1,136 @@
+# AGENTS.md
+
+Instructions for AI agents and automated tooling working in this repository.
+
+## Project context
+
+LabKit-Ruby (`gitlab-labkit` on RubyGems) is GitLab's Ruby SDK for cross-project infrastructure concerns: request context and correlation, structured logging, tracing, metrics, SLIs, and rate limiting.
+It is consumed by GitLab Rails and other Ruby services, so every public API is a compatibility commitment.
+
+It is one of several LabKit SDKs.
+The others are Go ([labkit](https://gitlab.com/gitlab-org/labkit)), Rust ([labkit-rs](https://gitlab.com/gitlab-org/rust/labkit-rs)), and Python ([labkit-python](https://gitlab.com/gitlab-org/labkit-python)).
+Behaviour that services observe, and anything written to a shared store, must be the same in every SDK.
+The contract lives in [labkit-spec](https://gitlab.com/gitlab-org/quality/tooling/labkit-spec), and its conformance harness is the judge.
+
+### Layout
+
+One gem, one `Labkit` namespace, one directory per capability under `lib/labkit/`.
+`lib/gitlab-labkit.rb` autoloads each capability unless the table says otherwise, so requiring the gem stays cheap and callers load only what they touch.
+
+| Module | Directory | Notes |
+| --- | --- | --- |
+| `Labkit::Context`, `Labkit::Correlation` | `lib/labkit/context.rb`, `lib/labkit/correlation/` | Request context for logs and propagation |
+| `Labkit::Logging` | `lib/labkit/logging/` | Log sanitisation and JSON formatting |
+| `Labkit::Tracing` | `lib/labkit/tracing/` | OpenTelemetry and legacy OpenTracing |
+| `Labkit::Metrics` | `lib/labkit/metrics/` | Prometheus client wrappers |
+| `Labkit::ApplicationSli`, `Labkit::UserExperienceSli` | `lib/labkit/application_sli/`, `lib/labkit/user_experience_sli/` | Apdex and error-rate SLIs |
+| `Labkit::RateLimit` | `lib/labkit/rate_limit/` | Rules-based, Redis-backed rate limiting, see below |
+| `Labkit::Middleware` | `lib/labkit/middleware/` | Rack and Sidekiq middleware for context, tracing, and SLIs |
+| `Labkit::JsonSchema` | `lib/labkit/json_schema/` | `RefResolver` for remote `$ref` in JSON schemas. Not autoloaded; required by `UserExperienceSli` |
+| `Labkit::FIPS` | `lib/labkit/fips.rb` | FIPS mode detection and OpenSSL digest substitution |
+| `Labkit::System` | `lib/labkit/system.rb` | Monotonic clock helper used by metrics, tracing, and logging |
+| `Labkit::Redis` | `lib/labkit/redis/` | Redis helpers shared by capabilities |
+| `Labkit::Fields` | `lib/labkit/fields.rb` | Generated by labkit-spec CI from `schema/fields.yaml`. Change the field there, not here |
+| `Labkit::RSpec` | `lib/labkit/rspec/` | Matchers for consumers' test suites. Not autoloaded; `require "labkit/rspec/matchers"` |
+
+`lib/labkit/*_publisher.rb` hook Excon, HTTPClient, and Net::HTTP to publish outbound request notifications.
+
+Modules with their own README (`lib/labkit/<module>/README.md`) document their public API there.
+Update that README in the same MR as a behaviour change.
+
+## Commands
+
+```shell
+bundle install
+bundle exec rake verify                        # rspec + rubocop, what CI runs
+bundle exec rake fix                           # rubocop autocorrect
+bundle exec rspec spec/labkit/<module>         # one module's specs
+bundle exec rake console                       # IRB with the gem loaded
+```
+
+Specs that need Redis use the instance at `LABKIT_TEST_REDIS_URL`, default `redis://localhost:6390/0`.
+If nothing answers there and `LABKIT_TEST_REDIS_URL` is unset, the suite starts one with `docker compose up -d redis` and stops it at exit.
+A Redis already listening on that URL is used as is and left running.
+Autostart is off when `LABKIT_TEST_REDIS_URL` is set, even to the default value, when `CI` is set, or when `LABKIT_TEST_REDIS_NO_AUTOSTART=1` is set.
+In those cases, start Redis yourself.
+
+Style is `gitlab-styles` via RuboCop with `NewCops: enable`.
+Do not edit `.rubocop_todo.yml` to silence a new offence; fix the code.
+Tool versions come from `.tool-versions` through mise.
+
+## CI
+
+- `rspec` runs the suite with a Redis service.
+- `ruby-versions` and `legacy-ruby-versions` repeat it on Ruby 3.4 and 3.3. The versions are set in `.gitlab-ci.yml`, not read from the gemspec.
+- `conformance-spec` triggers a downstream pipeline in labkit-spec that checks out this MR's commit and runs the conformance harness against it.
+  It runs when `lib/`, the gemspec, the Gemfile, or `.gitlab-ci.yml` change, and a red downstream run blocks the merge.
+  Renovate's bot user cannot start pipelines in labkit-spec, so on its MRs the job has `allow_failure: true` and a human rerun is the gate.
+- Danger runs the shared `gitlab-dangerfiles` checks except changelog and commit message, which semantic-release owns.
+
+## Commits, MRs, and releases
+
+Conventional Commits: `feat`, `fix`, `perf`, `revert`, `docs`, `refactor`, `test`, `chore`, `ci`, `style`.
+Scope is the module, for example `fix(rate_limit): ...`.
+
+Releases are cut from `master` and the `N-N-stable` branches by semantic-release with the `conventionalcommits` preset, so the commit type decides the version bump.
+
+| Type | Release |
+| --- | --- |
+| `feat!`, or any type with a `BREAKING CHANGE:` footer | major |
+| `feat` | minor |
+| `fix`, `perf`, `revert` | patch |
+| `docs`, `refactor`, `test`, `chore`, `ci`, `style` | none |
+
+There is no hand-edited changelog.
+
+Public APIs stay backward compatible.
+Add keyword arguments with defaults; do not add required parameters or rename public methods.
+Keep an MR to one concern, and separate mechanical changes such as renames from behavioural ones.
+
+## Rate limiting
+
+`Labkit::RateLimit` is documented in `lib/labkit/rate_limit/README.md`.
+It is the one capability that shares state across SDKs: services in any language enforce the same limits against the same Redis.
+That makes the Redis key shape and the Lua scripts as much a contract as the HTTP headers, so changes here follow stricter rules than the rest of the gem.
+
+### Where each SDK keeps it
+
+| SDK | Repository | Module | Tests | Status |
+| --- | --- | --- | --- | --- |
+| Ruby (this repository) | gitlab-org/ruby/gems/labkit-ruby | `lib/labkit/rate_limit/` | `spec/labkit/rate_limit/` | released |
+| Go | gitlab-org/labkit | `v2/ratelimit/` | `v2/ratelimit/*_test.go`, run with `go -C v2 test ./ratelimit/...` | released |
+| Rust | gitlab-org/rust/labkit-rs | in progress | | not released, skip |
+| Python | gitlab-org/labkit-python | in progress | | not released, skip |
+| Spec | gitlab-org/quality/tooling/labkit-spec | `conformance/README.md` ("v1 decisions"), `conformance/ratelimit_scenarios/*.json`, `conformance/aspect_ratelimit.go` | `conformance/` | judge |
+
+### The three layers
+
+Every SDK must agree on three layers.
+This section defines the layers; the current values (key grammar, header names, counting rules, metric names, log fields) live in labkit-spec, in the "v1 decisions" list in `conformance/README.md` and the scenarios under `conformance/ratelimit_scenarios/`.
+If this file and labkit-spec disagree, labkit-spec wins.
+
+1. **Storage contract.**
+   Anything written to or read from Redis: key shape and prefix, how values are encoded, TTL rules, and the Lua scripts.
+   Two SDKs sharing one Redis with different storage rules keep two counters for one limit.
+   Never change this layer in one SDK.
+   It changes in labkit-spec first, then every SDK follows.
+2. **Observable contract.**
+   Anything a caller or an operator can see: response status and headers, the counting rule that decides a block, log line messages and field sets, metric families and labels.
+   Also changes in labkit-spec first.
+3. **Behaviour within the contract.**
+   Input validation and edge cases the contract already implies, where one SDK does something the contract does not allow.
+   These may be fixed SDK by SDK, and every SDK should end up the same.
+
+A change that mixes layers is governed by the strictest one: storage, then observable, then behaviour.
+When a change does not fit one layer clearly, say so in the MR instead of picking one.
+
+### Rules for rate-limit changes
+
+- A change to layer 1 or 2 opens a labkit-spec MR first and waits for it to merge.
+- A change to layer 3 should be checked against the Go SDK.
+  If Go has the same gap, say so in the MR so it can be ported.
+- When a review finds a divergence between SDKs, a conformance scenario in labkit-spec must follow in the same week, so the harness sees the gap next time.
+  The author of the MR where the divergence was found owns this.
+  Mention the sync agent on the review thread to have it draft the scenario MR; if it cannot, open a labkit-spec issue and link it from the thread.
+- Never edit Lua scripts, key construction, header names, metric names, or log field names to fix a Ruby-only bug.
+  If a fix seems to need that, it is a contract change.

data/gitlab-labkit.gemspec

@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "pg_query", ">= 6.1.0", "< 7.0"
   spec.add_runtime_dependency "prometheus-client-mmap", ">= 1.2", "< 2.0"
   spec.add_runtime_dependency "redis", "> 3.0.0", "< 6.0.0"
+  spec.add_runtime_dependency "thrift", "< 0.25" # Pinned for jaeger-client 1.1.0 compatibility; thrift 0.25 requires transports to implement message_boundaries?
 
   # Please maintain alphabetical order for dev dependencies
   spec.add_development_dependency "excon", "~> 0.78.1"

data/lib/labkit/rate_limit/README.md

@@ -207,17 +207,63 @@ A `match` hash gates whether a rule applies. Each value is normalised through
 | plain value       | `eq`     | `match: { user: nil }`, `match: { method: "POST" }`    |
 | `Regexp`          | `re`     | `match: { endpoint: %r{\A/api/} }`                     |
 | `{ eq: <value> }` | `eq`     | `match: { method: { eq: "POST" } }` (YAML-friendly)    |
+| `{ ne: <value> }` | `ne`     | `match: { method: { ne: "OPTIONS" } }`                 |
 | `{ re: <source> }`| `re`     | `match: { endpoint: { re: '\A/api/' } }` (YAML-friendly) |
+| `{ nre: <source> }`| `nre`   | `match: { endpoint: { nre: '\A/api/' } }`              |
 | `{ oneOf: <Array> }` | `oneOf` | `match: { user: { oneOf: ["7", "42"] } }` (YAML-friendly) |
+| `{ noneOf: <Array> }` | `noneOf` | `match: { plan: { noneOf: ["premium"] } }`         |
+| `Array` of matchers | `all` | `match: { endpoint: [%r{\A/api/}, { nre: 'internal' }] }` |
 
-`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' }`).
+`re` and `nre` coerce the identifier value via `#to_s` before matching, so they
+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.
+`{ oneOf: [1] }` does not match `1.0`). `noneOf` is its complement.
+
+An Array means **AND**, so one identifier key can carry several predicates:
+
+```yaml
+endpoint:
+  - nre: '/oauth/'
+  - nre: '\A/api/'
+  - nre: '\A/-/(?:health|liveness|readiness|metrics)'
+```
+
+Its entries must be matcher Hashes or bare `Regexp`s, the two shapes that
+already mean "a matcher" on their own. An Array of plain values is rejected.
+A value meant as one matcher, arriving as a list, therefore fails loudly rather
+than becoming a membership test. Membership is spelled `{ oneOf: [...] }`.
+
+An Array holds matchers, not other Arrays, so a match value nests three deep at
+most: an Array, a matcher Hash inside it, and that Hash's `oneOf` list. A value
+nesting deeper than `Matcher::MAX_NESTING_DEPTH` is rejected when the rule is
+built.
+
+#### Negation and absent keys
+
+`ne`, `nre` and `noneOf` are plain complements of their positive forms, with no
+special case for a missing key. The `Evaluator` looks an identifier key up
+rather than requiring it, so an absent key reaches the matcher as `nil`, and a
+complement is therefore **true** for one: a request with no `endpoint` is not a
+request to an excluded endpoint.
+
+That widens a rule rather than narrowing it. A rule that should apply only when
+the key is present says so, with a presence matcher alongside the exclusions:
+
+```ruby
+match: { endpoint: [/./, { nre: '\A/api/' }] }
+```
+
+Since this follows from inversion, a matcher that does accept `nil` inverts the
+other way: `{ ne: nil }`, `{ noneOf: [nil] }` and `{ nre: '^$' }` are all false
+for an absent key, the last because `nil.to_s` is `""`.
+
+There is no cap on regex source length. Rules are written by operators, and the
+only bound on a pattern is `Matcher::MATCH_TIMEOUT_SECONDS`, a 50ms wall-clock
+budget applied per compiled `Regexp`.
 
 Glob and prefix matchers are intentionally out of scope.
 

data/lib/labkit/rate_limit/matcher.rb

@@ -12,27 +12,49 @@ module Labkit
     #   - any plain value (String, Symbol, Integer, ...) -> :eq matcher
     #   - a Regexp instance                              -> :re matcher (Ruby convenience)
     #   - { eq: <value> }                                -> :eq matcher (canonical, YAML-compatible)
+    #   - { ne: <value> }                                -> :ne matcher (complement of :eq)
     #   - { re: <String|Regexp> }                        -> :re matcher (canonical, YAML-compatible)
+    #   - { nre: <String|Regexp> }                       -> :nre matcher (complement of :re)
     #   - { oneOf: <Array> }                             -> :oneOf matcher (set membership, YAML-compatible)
+    #   - { noneOf: <Array> }                            -> :noneOf matcher (complement of :oneOf)
+    #   - [ <matcher>, <matcher>, ... ]                  -> :all matcher (every entry must match)
     #
-    # 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.
+    # An Array means AND, so several predicates can apply to one identifier key.
+    # Its entries must be matcher Hashes or bare Regexps, the two shapes that
+    # already mean "a matcher" on their own. An Array of plain values is
+    # rejected, so a value that was meant as a single matcher but arrived as a
+    # list fails loudly instead of silently becoming a membership test. An Array
+    # holds matchers rather than other Arrays, so a match value nests at most
+    # MAX_NESTING_DEPTH deep; see too_deeply_nested?.
     #
-    # :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).
+    # :oneOf and :noneOf 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
     # 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).
+    # The :re and :nre matchers coerce 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).
+    #
+    # Each negation matcher is the plain complement of its positive form, with
+    # no special case for a missing key. Evaluator passes identifier[key], so an
+    # absent key arrives as nil, and the complement is therefore usually true
+    # for one: a request with no path is not a request to an excluded path. A
+    # rule that should apply only when the key is present says so, by adding a
+    # presence matcher alongside the exclusions:
+    #
+    #   path: [/./, { nre: '\A/api/' }]
     class Matcher < Data.define(:type, :value)
-      KNOWN_HASH_KEYS = %i[eq re oneOf].freeze
-      MAX_REGEX_SOURCE_LENGTH = 200
+      KNOWN_HASH_KEYS = %i[eq ne re nre oneOf noneOf].freeze
       ERROR_INSPECT_LIMIT = 80
+      # No Hash or Array may sit this many levels below the match value, which
+      # is level 0. The deepest valid shape is an Array (0) holding a matcher
+      # Hash (1) whose :oneOf list (2) holds plain values; see
+      # too_deeply_nested?.
+      MAX_NESTING_DEPTH = 3
 
       # Wall-clock budget for a single #match? call. Without it a match is
       # bounded only by whatever global the host sets (40s in GitLab Rails,
@@ -45,16 +67,23 @@ module Labkit
       # timeouts were wall-clock stalls, since Ruby counts real time and GC
       # pauses on GitLab's git fleet have a p50 of ~72ms. Under 4x CPU
       # oversubscription 50ms still fires on 0.16% of those matches, 5ms 1.33%.
+      #
+      # This timeout is the only bound on a pattern. There is no cap on regex
+      # source length: rules are written by operators rather than end users, and
+      # a cap that applied to {re: "..."} but not to a bare Regexp bounded
+      # nothing in practice, since callers pass Regexp constants.
       MATCH_TIMEOUT_SECONDS = 0.05
 
       def self.build(input)
+        raise ArgumentError, nesting_error(input) if too_deeply_nested?(input)
+
         case input
         when Regexp
-          new(type: :re, value: with_match_timeout(input))
+          new(type: :re, value: with_match_timeout(:re, input))
         when Hash
           from_hash(input)
         when Array
-          raise ArgumentError, invalid_shape_error(input)
+          compose(input)
         else
           new(type: :eq, value: input)
         end
@@ -64,6 +93,15 @@ module Labkit
         raise ArgumentError, invalid_shape_error(input) if input.size != 1
 
         type, source = input.first
+
+        # Identifier rejects keys the same way. Without this, a key such as an
+        # Integer or nil leaves NoMethodError for the caller instead of the
+        # ArgumentError every other bad shape raises.
+        unless type.respond_to?(:to_sym)
+          raise ArgumentError,
+            "rate-limit match value type key #{truncate_for_error(type)} must be a String or Symbol"
+        end
+
         type_sym = type.to_sym
 
         unless KNOWN_HASH_KEYS.include?(type_sym)
@@ -77,31 +115,45 @@ module Labkit
 
       def self.compile(type_sym, source)
         case type_sym
-        when :eq
-          new(type: :eq, value: source)
-        when :oneOf
+        when :eq, :ne
+          new(type: type_sym, value: source)
+        when :oneOf, :noneOf
           unless source.is_a?(Array)
             raise ArgumentError,
-              "rate-limit match value {oneOf: ...} must be an Array, got #{truncate_for_error(source)}"
+              "rate-limit match value {#{type_sym}: ...} 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
+          # {oneOf: []} matches nothing, so the rule never applies and no harm
+          # follows. Its complement matches everything, which is an exclusion
+          # that excludes nothing: rejected for the same reason an empty Array
+          # of matchers is.
+          if type_sym == :noneOf && source.empty?
             raise ArgumentError,
-              "rate-limit match value {re: ...} source exceeds #{MAX_REGEX_SOURCE_LENGTH} characters"
+              "rate-limit match value {noneOf: []} must not be empty, it matches everything"
           end
 
-          begin
-            new(type: :re, value: with_match_timeout(source))
-          rescue RegexpError, TypeError => e
-            raise ArgumentError,
-              "rate-limit match value {re: #{truncate_for_error(source)}} failed to compile: #{e.message}"
-          end
+          new(type: type_sym, value: Set.new(source).freeze)
+        when :re, :nre
+          new(type: type_sym, value: with_match_timeout(type_sym, source))
         end
       end
       private_class_method :compile
 
+      # Builds the :all matcher behind the Array form. Entries go back through
+      # .build, which is what keeps a nested regex bounded by the match timeout.
+      def self.compose(input)
+        raise ArgumentError, "rate-limit match value [] must not be empty" if input.empty?
+
+        unless input.all? { |entry| entry.is_a?(Hash) || entry.is_a?(Regexp) }
+          raise ArgumentError,
+            "rate-limit match value Array entries must each be a matcher Hash or Regexp, " \
+              "got #{truncate_for_error(input)}"
+        end
+
+        new(type: :all, value: input.map { |entry| build(entry) }.freeze)
+      end
+      private_class_method :compose
+
       # Compiles +source+ (a String pattern or an existing Regexp) into a
       # Regexp bounded by MATCH_TIMEOUT_SECONDS.
       #
@@ -116,7 +168,7 @@ module Labkit
       # Recompiling an existing Regexp preserves its source and options
       # (including the fixed-encoding flags) and therefore +#==+; only object
       # identity changes.
-      def self.with_match_timeout(source)
+      def self.with_match_timeout(key, source)
         return source if source.is_a?(Regexp) && source.timeout
 
         if source.is_a?(Regexp)
@@ -124,12 +176,19 @@ module Labkit
         else
           Regexp.new(source, timeout: MATCH_TIMEOUT_SECONDS)
         end
+      rescue RegexpError, TypeError => e
+        raise ArgumentError,
+          "rate-limit match value {#{key}: #{truncate_for_error(source)}} failed to compile: #{e.message}"
       end
 
       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: [...]}, " \
+        # No key list here: this fires on the shape, and from_hash names the
+        # accepted keys when the shape is right but the key is not. Keeping the
+        # fixed part short is also what lets truncate_for_error bound the whole
+        # message.
+        "rate-limit match value must be a single-key Hash, or an Array of matchers, " \
           "got #{truncate_for_error(input)}"
       end
       private_class_method :invalid_shape_error
@@ -140,14 +199,65 @@ module Labkit
       end
       private_class_method :truncate_for_error
 
+      def self.nesting_error(input)
+        # Does not inspect the input: it is too deep to render, which is the
+        # reason this fires. The class is the only hint available cheaply, and
+        # the nesting may be in a key or a value.
+        "rate-limit match value nests deeper than #{MAX_NESTING_DEPTH} levels (#{input.class})"
+      end
+      private_class_method :nesting_error
+
+      # A valid match value nests three deep at most: an Array of matcher
+      # Hashes whose :oneOf value is an Array of plain values. Anything past
+      # MAX_NESTING_DEPTH is rejected rather than built.
+      #
+      # The check is iterative because the alternative is finding out through
+      # #inspect, which recurses once per level while rendering an error
+      # message. Rules are built at boot and SystemStackError is not a
+      # StandardError, so that would take the process down rather than reject
+      # one rule, and rescuing it is not an option either: the VM aborts on a
+      # second overflow in the same process.
+      def self.too_deeply_nested?(input)
+        # A flat stack of node, depth pairs, so a visit allocates no Array. The
+        # pops must mirror the pushes: depth comes off first, then its node.
+        stack = [input, 0]
+
+        until stack.empty?
+          depth = stack.pop
+          node = stack.pop
+          next unless node.is_a?(Hash) || node.is_a?(Array)
+          return true if depth >= MAX_NESTING_DEPTH
+
+          # Keys as well as values: #inspect renders both, so a deeply nested
+          # key overflows the same way a deeply nested value does.
+          if node.is_a?(Hash)
+            node.each { |key, value| stack.push(key, depth + 1, value, depth + 1) }
+          else
+            node.each { |child| stack.push(child, depth + 1) }
+          end
+        end
+
+        false
+      end
+      private_class_method :too_deeply_nested?
+
       def match?(identifier_value)
         case type
         when :eq
           value == identifier_value
+        when :ne
+          value != identifier_value
         when :oneOf
           value.include?(identifier_value)
+        when :noneOf
+          # exclude? is ActiveSupport, and nothing in rate_limit requires it.
+          !value.include?(identifier_value) # rubocop:disable Rails/NegateInclude
         when :re
           value.match?(identifier_value.to_s)
+        when :nre
+          !value.match?(identifier_value.to_s)
+        when :all
+          value.all? { |matcher| matcher.match?(identifier_value) }
         else
           raise ArgumentError, "unknown matcher type: #{type.inspect}"
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 5.2.1
+  version: 5.3.1
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -277,6 +277,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: 6.0.0
+- !ruby/object:Gem::Dependency
+  name: thrift
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.25'
 - !ruby/object:Gem::Dependency
   name: excon
   requirement: !ruby/object:Gem::Requirement
@@ -568,6 +582,7 @@ files:
 - ".rufo"
 - ".tool-versions"
 - ".yamllint.yaml"
+- AGENTS.md
 - CODEOWNERS
 - CONTRIBUTING.md
 - Dangerfile