gitlab-labkit 1.20.1 → 1.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b916b3579ca06fa9a40b34d2bac1d9ffb5bcb8a51415ad9438956c546400164
-  data.tar.gz: a680e485958792ac93e5be3fca0c7598db2c029349d6c7aa3c34a039daf2e350
+  metadata.gz: 43d394fdecdc0275e1ddab3a28ae7824f907e21637c4d06b3cc183a801df9377
+  data.tar.gz: 18632e75c51ec22c6b78079c59476f736b3b3b298c7988fbf4a49c9505c4d05e
 SHA512:
-  metadata.gz: 53acf37dbe0f4416c5952dfba12e3df3156f233243c69580bb3dfdef6b9727f73d586151a9809225e9a99d537e2499da4f66061c197462debc76d3b3c633160a
-  data.tar.gz: bd46d460f292290670b62801a5cb84958b187e086b662d9537df95d0ddc9af6bc1c956050d051a4c14383209b07923fbcfab0992d59c689a5c794811de0a43a2
+  metadata.gz: d56453b6af992b51da987bec68fd990fefc808b68be96702c3b4274ae609a773139b39bb5609032ed9148a7427976bd64ea0566fa0c8354582e4d4d4135d481e
+  data.tar.gz: f8d71107b36351983b8a1da70b9a43624b2eb73e000b37fd45cad03606749c84a2da0282d1e02cd7f5a1b687e2e030717fc1770f2671d05175a7cd4d9eb9bad1

data/.copier-answers.yml

@@ -3,9 +3,10 @@
 # See the project for instructions on how to update the project
 #
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: v1.46.0
+_commit: v1.48.0
 _src_path: https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git
 ee_licensed: false
+gitlab_namespace: gitlab-org/ruby/gems
 golang: false
 helm: false
 initial_codeowners: '@reprazent @andrewn @mkaeppler @ayufan'

data/.gitignore

@@ -3,3 +3,4 @@ Gemfile.lock
 node_modules
 .bundle
 /.env.sh
+.idea/

data/.gitlab-ci.yml

@@ -27,6 +27,16 @@ include:
 
   - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v3.24
 
+# Attach a redis service to the rspec job from common-ci-tasks/ruby-build.
+# GitLab merges keys when a local job has the same name as an included one,
+# so this augments the base job (and is inherited by anything that extends it).
+rspec:
+  services:
+    - name: redis:7-alpine
+      alias: redis
+  variables:
+    LABKIT_TEST_REDIS_URL: redis://redis
+
 ruby-versions:
   extends: rspec
   image: ${CI_REGISTRY}/gitlab-com/gl-infra/common-ci-tasks-images/ruby:${RUBY_VERSION}

data/README.md

@@ -24,6 +24,7 @@ LabKit-Ruby provides functionality in a number of areas:
 1. `Labkit::FIPS` for checking for FIPS mode and using FIPS-compliant algorithms.
 1. `Labkit::Logging` for sanitizing log messages.
 1. `Labkit::Metrics` for metrics. More on the [README](./lib/labkit/metrics/README.md).
+1. `Labkit::RateLimit` for rules-based, Redis-backed rate limiting. More on the [README](./lib/labkit/rate_limit/README.md).
 1. `Labkit::RSpec` for RSpec matchers to test Labkit functionality (requires selective loading). More on the [README](./lib/labkit/rspec/README.md).
 1. `Labkit::Tracing` for handling and propagating distributed traces.
 
@@ -43,6 +44,16 @@ $ # Run tests, linters
 $ bundle exec rake verify
 ```
 
+Some specs require a real Redis instance. When you run the suite locally,
+it will automatically start one via `docker compose up -d redis` (see
+`docker-compose.yml`) and tear it down again when the test process exits.
+Redis is exposed on `localhost:6390` so it does not collide with a local
+GDK/Caproni Redis on the default port.
+
+To opt out of autostart (e.g. you've started Redis some other way), set
+`LABKIT_TEST_REDIS_URL` to a reachable instance, or
+`LABKIT_TEST_REDIS_NO_AUTOSTART=1` to fail loudly instead of spawning.
+
 Please also review the [development section of the LabKit (go) README](https://gitlab.com/gitlab-org/labkit#developing-labkit) for details of the LabKit architectural philosophy.
 
 To work on some of the scripts we use for releasing a new version,

data/docker-compose.yml

@@ -0,0 +1,10 @@
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6390:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 2s
+      retries: 5

data/exe/labkit-logging

@@ -176,7 +176,9 @@ module Labkit
           http.read_timeout = 30
           req = Net::HTTP::Get.new(uri.request_uri)
           req['PRIVATE-TOKEN'] = token
-          http.request(req)
+          resp = http.request(req)
+          abort "Unauthorized: check that your GitLab token is valid and has access to this project" if resp.is_a?(Net::HTTPUnauthorized) || resp.is_a?(Net::HTTPForbidden)
+          resp
         end
 
         def token

data/lib/labkit/rate_limit/README.md

@@ -0,0 +1,329 @@
+# Labkit::RateLimit
+
+`Labkit::RateLimit` is a rules-based rate limiter backed by Redis counters. It
+maintains a fixed-window counter per `(call-site, rule, characteristics)` tuple
+and decides whether each request is within the configured limit.
+
+The module is intentionally small: a `Limiter` is configured at boot with an
+ordered list of `Rule`s, and every request calls `Limiter#check(identifier)` to
+get back a `Result` describing what the caller should do.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    App[Application code] -->|"check(identifier)"| Limiter
+    Limiter -->|delegates| Evaluator
+    Evaluator -->|iterates ordered| Rules[Rule list]
+    Evaluator <-->|INCR / TTL / EXPIRE| Redis[(Redis)]
+    Evaluator -->|emits| Metrics[Prometheus metrics]
+    Evaluator -->|returns| Result
+    Result --> App
+```
+
+A `Limiter` is configured once per call site and holds an `Evaluator` plus the
+compiled `Rule` list. Every `check` call delegates to the same `Evaluator`,
+which iterates the rules in declaration order, talks to Redis, emits metrics,
+and builds a `Result`.
+
+## Configuration
+
+`Labkit::RateLimit.configure` sets a global Redis connection pool and logger
+that are reused across all `Limiter` instances unless a per-Limiter override is
+supplied:
+
+```ruby
+Labkit::RateLimit.configure do |c|
+  c.redis  = ConnectionPool.new(size: 5) { Redis.new(url: ENV["REDIS_URL"]) }
+  c.logger = Labkit::Logging::JsonLogger.new($stdout)
+end
+```
+
+The `redis` value must respond to `.with { |conn| ... }` and yield a connection
+that supports `incr`, `ttl`, `get`, `expire`, and `pipelined`. A
+`ConnectionPool` of `Redis` clients is the typical choice.
+
+The logger is used only for warnings (invalid rule names, fail-open errors,
+duplicate rule names in production). It defaults to a JSON logger writing to
+`$stdout`.
+
+## Defining a Limiter
+
+A `Limiter` is the unit of configuration for one call site (e.g. "rack
+requests", "graphql mutations", "ai actions"). Construct it once and reuse it:
+
+```ruby
+RACK_LIMITER = Labkit::RateLimit::Limiter.new(
+  name: "rack_request",
+  rules: [
+    Labkit::RateLimit::Rule.new(
+      name: "api_user",
+      limit: 600,
+      period: 60,
+      characteristics: [:user],
+      match: { endpoint: { re: '\A/api/' } }
+    ),
+    Labkit::RateLimit::Rule.new(
+      name: "unauthenticated",
+      limit: 60,
+      period: 60,
+      characteristics: [:ip],
+      match: { user: nil }
+    )
+  ]
+)
+```
+
+- `name` must match `/\A[a-z0-9_]+\z/`. It is used as the first segment of
+  every Redis counter key for this limiter, so renaming a `Limiter` abandons
+  any in-flight counters.
+- `rules` is an ordered array of `Rule` objects. The first rule whose `match`
+  hash is satisfied wins (with the exception of `:log` rules — see [Actions](#actions)).
+- `redis` and `logger` are optional; they fall back to the global
+  `Labkit::RateLimit.config` values.
+
+A `Labkit::RateLimit.check(name:, identifier:, rules:, ...)` convenience method
+exists for one-off cases that cannot cache a `Limiter` instance, but it
+allocates a fresh `Limiter` on every call and is not the recommended path.
+
+## Checking a request
+
+`Limiter#check(identifier)` increments the counter for the matched rule and
+returns a `Result`. `identifier` is either an `Identifier` or a plain `Hash`
+of caller attributes:
+
+```ruby
+result = RACK_LIMITER.check(
+  user:     current_user&.id,
+  ip:       request.ip,
+  endpoint: request.path
+)
+
+if result.exceeded? && result.action == :block
+  response.headers.merge!(result.to_response_headers)
+  render plain: "Too Many Requests", status: 429
+  return
+end
+```
+
+The `endpoint` key is treated specially: the query string is stripped at
+`Identifier` construction time so URLs that vary only by query parameter share
+the same counter.
+
+### Peeking without incrementing
+
+`Limiter#peek(identifier)` returns the same `Result` shape but does not
+mutate Redis. It is useful when one code path should account for the request
+(`check`) and another should gate a side-effect on whether the caller is
+already over-limit. `peek` skips `:log` rules — their state is unobservable
+without incrementing.
+
+## Identifier
+
+`Identifier` is a small value object wrapping a hash of caller attributes.
+You can pass a `Hash` to `check`/`peek` and `Limiter` will wrap it for you, or
+construct one explicitly:
+
+```ruby
+id = Labkit::RateLimit::Identifier.new(
+  user:     42,
+  ip:       "1.2.3.4",
+  endpoint: "/api/v4/projects/1?per_page=20"  # becomes "/api/v4/projects/1"
+)
+```
+
+Keys can be symbols or strings — they are normalised to symbols on the way
+in.
+
+## Rule
+
+A `Rule` is a `Data.define` value object with the following fields:
+
+| field             | meaning                                                                                                                                                              |
+|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `name`            | Stable identifier used in Redis keys and metric labels. Must match `/\A[a-z0-9_]+\z/`, max 64 chars. Renaming a rule abandons its in-flight counters.                |
+| `match`           | Hash of identifier key/value predicates that must **all** be satisfied for the rule to apply. Empty hash matches anything. See [Matchers](#matchers).                |
+| `limit`           | Integer request threshold per `period`. May be a callable resolved on every check.                                                                                   |
+| `period`          | Window length in seconds. May be a callable resolved on every check.                                                                                                 |
+| `action`          | What the result reports when the limit is exceeded. One of `:block`, `:log`, `:allow`. Default `:block`. See [Actions](#actions).                                    |
+| `characteristics` | Array of identifier keys whose values are folded into the Redis counter key. Each unique combination gets its own counter.                                           |
+
+Making `limit` or `period` callable is the supported pattern for
+runtime-tunable thresholds (e.g. feature flags or database-backed settings):
+
+```ruby
+Labkit::RateLimit::Rule.new(
+  name: "api_user",
+  limit:  -> { Settings.rate_limit_api_user_per_minute },
+  period: 60,
+  characteristics: [:user]
+)
+```
+
+### Matchers
+
+A `match` hash gates whether a rule applies. Each value is normalised through
+`Matcher.build`:
+
+| input shape       | matcher  | example                                                |
+|-------------------|----------|--------------------------------------------------------|
+| 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)    |
+| `{ re: <source> }`| `re`     | `match: { endpoint: { re: '\A/api/' } }` (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' }`).
+
+Glob and prefix matchers are intentionally out of scope.
+
+### Evaluation flow
+
+`check` walks the rule list in order. The first **terminating** rule wins;
+`:log` rules count but do not terminate, so they cannot disable a following
+`:block` rule. A pure `:log`-only path still emits one `rule="unmatched"`
+metric increment because no terminating rule fired.
+
+```mermaid
+flowchart TD
+    Start([check identifier]) --> Iter{Next rule?}
+    Iter -->|yes| Match{rule.match<br/>all satisfied?}
+    Match -->|no| Iter
+    Match -->|yes| Eval["INCR Redis counter<br/>(see Redis sequence below)"]
+    Eval --> Build[Build Result<br/>resolve limit/period]
+    Build --> Emit[Emit calls_total + limit/period gauges]
+    Emit --> Act{rule.action}
+    Act -->|":log<br/>(non-terminating)"| Iter
+    Act -->|:block or :allow| Return([Return Result])
+    Iter -->|no more rules| Unmatched[Emit calls_total<br/>rule=unmatched, action=allow]
+    Unmatched --> ReturnUnmatched([Return matched=false<br/>action=:allow])
+    Eval -. StandardError .-> Error[Emit errors_total<br/>log warn]
+    Error --> ReturnErr([Return error=true<br/>action=:allow])
+```
+
+### Actions
+
+The rule's `action` controls how the `Result` reports an over-limit hit. The
+counter is always incremented when a rule matches, regardless of `action`:
+
+- `:block` — when exceeded, `Result#action` is `:block`. Caller should reject
+  the request (e.g. with HTTP 429). When under the limit, action is `:allow`.
+- `:log` — **non-terminating**. The rule counts the request and records
+  metrics, but evaluation continues to the next rule. This is the mechanism
+  for shadow rules during rollout: stack a `:log` rule and a `:block` rule
+  together and the `:log` rule cannot disable the `:block` rule. Note that a
+  pure `:log`-only check still emits one `rule="unmatched"` metric entry
+  because no terminating rule fired.
+- `:allow` — when exceeded, `Result#action` is `:allow` (rather than
+  `:block`). Useful for "always allow this caller even if they're over the
+  limit" cases while still observing them via metrics. Evaluation terminates
+  on the first match.
+
+### Redis keys
+
+Each matched check writes a key shaped:
+
+```
+labkit:rl:<limiter_name>:<rule_name>:<char>:<value>[:<char>:<value>...]
+```
+
+Characteristic values longer than 200 bytes are replaced with a SHA-256
+hexdigest to bound key length. Missing or empty characteristic values are
+encoded as `_unknown_`. The TTL is set on the first write of each window
+(`count == 1`) and is not extended on subsequent INCRs, so the window is a
+true fixed window starting at the first request, not a sliding window.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant E as Evaluator
+    participant P as Connection pool
+    participant R as Redis
+
+    E->>P: pool.with { |conn| ... }
+    P-->>E: conn
+    E->>R: PIPELINE { INCR key, TTL key }
+    R-->>E: [count, ttl]
+    alt count == 1 (first write of window)
+        E->>R: EXPIRE key period
+        R-->>E: 1
+        Note over E: ttl returned is -1 here;<br/>build_result falls back to<br/>resolved_period for reset_at.
+    else count > 1
+        Note over E: TTL is not extended:<br/>fixed window from first write.
+    end
+    E-->>P: release conn
+```
+
+`peek` follows the same shape but uses `GET` instead of `INCR` and never
+issues `EXPIRE`. A missing key (`GET → nil`, `TTL → -2`) is reported as
+`count = 0` and the window is treated as not-yet-started.
+
+## Result
+
+`Result` carries the decision back to the caller:
+
+```ruby
+result.matched?           # => true if some rule matched
+result.exceeded?          # => true if the matched rule's counter > limit
+result.action             # => :block | :log | :allow
+result.rule               # => the matched Rule, or nil
+result.error?             # => true if Redis failed (see Fail-open)
+result.info               # => Result::Info or nil
+result.to_response_headers
+# => { "RateLimit-Limit" => "...", "RateLimit-Remaining" => "...", "RateLimit-Reset" => "<unix-ts>" }
+```
+
+`Result::Info` holds the per-window counter snapshot:
+
+| field             | meaning                                                          |
+|-------------------|------------------------------------------------------------------|
+| `resolved_limit`  | The evaluated `Integer` limit for this check.                    |
+| `resolved_period` | The evaluated `Integer` period in seconds for this check.        |
+| `count`           | Raw INCR value; useful for utilization-ratio metrics.            |
+| `remaining`       | `[resolved_limit - count, 0].max`.                               |
+| `reset_at`        | Best-effort UTC `Time` when the window resets (advisory only).   |
+
+`to_response_headers` returns `{}` for an unmatched or error result, so it is
+safe to merge unconditionally.
+
+## Fail-open
+
+The evaluator wraps `check` and `peek` in a broad rescue. Any `StandardError`
+(Redis connection failure, timeout, OOM in user-supplied callables, …) is
+logged at WARN with `message: "rate_limit_error"` and returned as a
+`Result(matched: false, error: true, action: :allow)`. The
+`gitlab_labkit_rate_limiter_errors_total` counter is incremented. The caller
+should treat the request as allowed.
+
+## Metrics
+
+`Labkit::RateLimit::Metrics` emits the following Prometheus metrics through
+`Labkit::Metrics::Client`:
+
+| metric                                          | type    | labels                              | meaning                                                              |
+|-------------------------------------------------|---------|-------------------------------------|----------------------------------------------------------------------|
+| `gitlab_labkit_rate_limiter_calls_total`        | counter | `rate_limiter`, `rule`, `action`    | One increment per terminating decision; also incremented per matched `:log` rule. `action` is one of `"allow"`, `"block"`, `"log"`. `rule="unmatched", action="allow"` when no rule terminated. |
+| `gitlab_labkit_rate_limiter_errors_total`       | counter | `rate_limiter`                      | Fail-open events (any `StandardError` in the labkit path).            |
+| `gitlab_labkit_rate_limiter_limit`              | gauge   | `rate_limiter`, `rule`              | Resolved limit at the last check (useful when `limit:` is callable). |
+| `gitlab_labkit_rate_limiter_period_seconds`     | gauge   | `rate_limiter`, `rule`              | Resolved period at the last check.                                   |
+
+Because `:log` rules do not terminate, a single `check` call can emit
+**multiple** `calls_total` increments: one per `:log` rule that matched, plus
+one for the terminating decision (or `rule="unmatched"` if no terminating
+rule fired).
+
+## Dev/test vs production guards
+
+`Limiter.new` and `Rule.new` validate names and configuration. In
+`Labkit.dev_or_test?` mode (`RAILS_ENV` set to `development` or `test`), they
+raise `ArgumentError` on:
+
+- invalid limiter or rule names
+- duplicate rule names within a single `Limiter`
+- unknown `action` values
+- rule names longer than 64 characters
+
+In production, the same conditions are downgraded: invalid names are
+sanitised (and the original/sanitised pair is logged), duplicate rule names
+are dropped (first occurrence wins), and a warning is logged. This keeps a
+misconfiguration from taking the application down at boot.

data/lib/labkit/rate_limit/rule.rb

@@ -14,7 +14,8 @@ module Labkit
     # period          - window in seconds; may be a callable (resolved per check)
     # 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)
+    #                   (count but always permit; terminates evaluation on match
+    #                   regardless of whether the limit was exceeded)
     # characteristics - identifier keys used to build the compound Redis counter key
     #
     # +name+ must be a lowercase alphanumeric-and-underscore string of at most 64

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 1.20.1
+  version: 1.21.0
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -547,6 +547,7 @@ files:
 - config/user_experience_slis/testing_sample.yml
 - doc/FIELD_STANDARDIZATION.md
 - doc/architecture/decisions/001_field_standardization_dynamic_runtime_linting.md
+- docker-compose.yml
 - exe/labkit-logging
 - gitlab-labkit.gemspec
 - lib/gitlab-labkit.rb
@@ -599,6 +600,7 @@ files:
 - lib/labkit/middleware/sidekiq/user_experience_sli/server.rb
 - lib/labkit/net_http_publisher.rb
 - lib/labkit/rate_limit.rb
+- lib/labkit/rate_limit/README.md
 - lib/labkit/rate_limit/configuration.rb
 - lib/labkit/rate_limit/evaluator.rb
 - lib/labkit/rate_limit/identifier.rb