gitlab-labkit 2.8.1 → 4.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ad3bb9ba369010544041c2ab2d2ec2d8610c535c5b2c5e592fe0e8313c56a66
-  data.tar.gz: 4fa90bdb331f44920cc9969603db7189e42dec21c7fab1d7593e91455de323c3
+  metadata.gz: 22a38c0fe1a2f28aa538b80348911947c6de64c16d7d870d24835332796faa99
+  data.tar.gz: 6259d696d178f3008aefdf91de71731c81d460cef08259555829f15d8abd462c
 SHA512:
-  metadata.gz: 21c914360a54bb30e914e7b6771781657463b3febd83b81634b88513f2986d7d9f25016bae84781b69918429a49c13fdfdf7da8581d385bc13adb698c8728f1d
-  data.tar.gz: e8b1b9f46c438e2608a1f12e55d2fd3f518586795dfb0327b08fed8bcd6496525fb0fba71c5212fdab45b45a3ca1b3b9c792dc212a838a98124be37d698fd823
+  metadata.gz: dd404f717fe9cee20cb544ad23cd5aa3195683ac0efe8bf8363988fdb8dcacc4fcaa817ac6f4cb3fcdb4f2e3d193c6d93cc13deea0344067e44fac7f3c593fb3
+  data.tar.gz: cc8d6bb5fe6fde8c17f969d4a708bd41901de5f9383f4821e3acf13a2eb35c240a80d18d3853ac5f29b689d7841df254f540233174646204358e698b9e0f643e

data/.gitlab/CODEOWNERS

@@ -1 +1 @@
-* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael
+* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael @sankalp_gl @hardikgala @nindurkar @ashs2

data/.gitlab-ci-asdf-versions.yml

@@ -1,5 +1,5 @@
 # DO NOT MANUALLY EDIT; Run ./scripts/update-asdf-version-variables.sh to update this
 variables:
-    GL_ASDF_RUBY_VERSION: "4.0.5"
+    GL_ASDF_RUBY_VERSION: "4.0.6"
     GL_ASDF_SHELLCHECK_VERSION: "0.11"
     GL_ASDF_SHFMT_VERSION: "3.13"

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@v4.22
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/standard-build@v4.36
 
   # 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@v4.22
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/ruby-build@v4.36
 
-  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v4.22
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v4.36
 
 # 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,

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: v4.22  # renovate:managed
+    rev: v4.36  # renovate:managed
 
     hooks:
       - id: shellcheck  # Run shellcheck for changed Shell files

data/.tool-versions

@@ -1,3 +1,3 @@
-ruby 4.0.5
+ruby 4.0.6
 shfmt 3.13
 shellcheck 0.11

data/CODEOWNERS

@@ -1,4 +1,4 @@
 # CODEOWNERS is used to lookup assignees for
 # Renovate Bot dependency change Merge Requests.
 # https://docs.renovatebot.com/configuration-options/#assigneesfromcodeowners
-* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael @e_forbes @M_Alvarez @mwoolf
+* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael @e_forbes @M_Alvarez @mwoolf @sankalp_gl @hardikgala @nindurkar @ashs2

data/lib/labkit/fields.rb

@@ -132,6 +132,12 @@ module Labkit
     # email reply.
     GL_SENT_NOTIFICATION_ID = "gl_sent_notification_id"
 
+    # Free-form supplementary details about a log event that do not have a
+    # dedicated field. Use sparingly for human-readable context. Avoid logging
+    # secrets or PII, and sanitize values that may contain control characters
+    # (e.g. newlines) to prevent log injection.
+    ADDITIONAL_DETAILS = "additional_details"
+
     # Maps each field constant to its logging field variant version.
     # A version of 0 means the field is not yet assigned to any variant.
     VARIANT_VERSION = {
@@ -172,6 +178,7 @@ module Labkit
       CALLER_ID => 1,
       ROOT_CALLER_ID => 0,
       GL_SENT_NOTIFICATION_ID => 0,
+      ADDITIONAL_DETAILS => 0,
     }.freeze
 
     # Get the constant name for a field value
@@ -192,7 +199,7 @@ module Labkit
 
       MAPPINGS = {
         Fields::CORRELATION_ID => %w[tags.correlation_id],
-        Fields::GL_USER_ID => %w[user_id userid extra.user_id extra.current_user_id meta.user_id],
+        Fields::GL_USER_ID => %w[user_id userid extra.user_id extra.current_user_id meta.user_id gitlab_user_id],
         Fields::GL_USER_NAME => %w[username extra.user meta.user],
         Fields::ERROR_MESSAGE => %w[error err error.message exception.message graphql_errors],
         Fields::HTTP_STATUS_CODE => %w[status_code extra.status status_text http_status],

data/lib/labkit/rate_limit/README.md

@@ -15,7 +15,7 @@ flowchart LR
     App[Application code] -->|"check(identifier)"| Limiter
     Limiter -->|delegates| Evaluator
     Evaluator -->|iterates ordered| Rules[Rule list]
-    Evaluator <-->|INCR / TTL / EXPIRE| Redis[(Redis)]
+    Evaluator <-->|EVALSHA / GET / TTL| Redis[(Redis)]
     Evaluator -->|emits| Metrics[Prometheus metrics]
     Evaluator -->|returns| Result
     Result --> App
@@ -77,8 +77,8 @@ RACK_LIMITER = Labkit::RateLimit::Limiter.new(
 - `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)).
+- `rules` is an ordered array of `Rule` objects. Every rule whose `match` hash
+  is satisfied is evaluated and counted (see [Evaluation flow](#evaluation-flow)).
 - `redis` and `logger` are optional; they fall back to the global
   `Labkit::RateLimit.config` values.
 
@@ -99,7 +99,7 @@ result = RACK_LIMITER.check(
   endpoint: request.path
 )
 
-if result.exceeded? && result.action == :block
+if result.action == :block
   response.headers.merge!(result.to_response_headers)
   render plain: "Too Many Requests", status: 429
   return
@@ -115,9 +115,34 @@ the same counter.
 `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. A matched `:skip` rule terminates `peek` the same way
-it terminates `check`: matched, `:allow`, no Redis read, no `info`.
+already over-limit. `peek` reads `:log` rules too: `check` can report a
+`:log` rule's evaluation, so excluding them would make `peek` answer a
+different question than `check`. A matched `:skip` rule terminates `peek`
+the same way it terminates `check`: matched, `:allow`, no Redis read, no
+`info`.
+
+### Clearing state
+
+`Limiter#clear(identifier)` deletes this limiter's counters for one
+identifier, along with any ban a rule carrying `ban_for` has written, and returns the
+number of keys removed.
+
+```ruby
+RACK_LIMITER.clear({ ip: "1.2.3.4" }) # => 2
+```
+
+Counters otherwise only disappear when their window expires; this is the only
+way to end one early. It exists for call sites where a later success should
+wipe earlier failures, such as an authentication ban cleared by a valid
+login.
+
+Every rule in the limiter is cleared, matched or not, because a caller
+clearing state after a success knows the identifier rather than which rules
+happened to match on the way in. Each rule is deleted in its own call, since
+rules do not share a Redis Cluster slot. Clearing an identifier with no state
+is a no-op returning `0`. A Redis failure fails open like `check`, leaving the
+rest of the state to expire on its own, and the return value counts whatever
+was removed before the failure.
 
 ## Identifier
 
@@ -146,8 +171,10 @@ A `Rule` is a `Data.define` value object with the following fields:
 | `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`, `:skip`. Default `:block`. See [Actions](#actions).                           |
+| `action`          | What the rule does when it matches. One of `:limit`, `:log`, `:skip`. Default `:limit`. See [Actions](#actions).                                                     |
 | `characteristics` | Array of identifier keys whose values are folded into the Redis counter key. Each unique combination gets its own counter.                                           |
+| `count_distinct`  | Optional identifier key. When set, the rule counts distinct values seen for that key within the window, backed by a Redis SET rather than a counter. Must not overlap `characteristics`. |
+| `ban_for`         | Optional ban duration, whole seconds, minimum 1. Changes the accounting; `action` still decides who is blocked. Rejected on `:skip`. May be a callable resolved on every check.     |
 
 Making `limit` or `period` callable is the supported pattern for
 runtime-tunable thresholds (e.g. feature flags or database-backed settings):
@@ -172,18 +199,52 @@ 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
 
-`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.
+`check` walks the rule list in order and evaluates **every** rule that matches:
+each one increments its own counter, and the request debits `cost` from all of
+them. Matching alone does not stop the walk. Only two things terminate it:
+
+- a matched `:skip` rule (bypass, nothing counted), and
+- a `:limit` rule that is **over its limit** — the request is rejected, so the
+  remaining rules cannot change the outcome. Rules declared after it are neither
+  counted nor evaluated, meaning a blocked request debits every rule up to and
+  including the one that blocked, and none after it.
+
+A `:limit` rule that is under its limit does not terminate, so it behaves
+exactly like `:log` until the moment it blocks.
+
+The returned `Result` collects one `Result::Evaluation` per counted rule
+(`result.evaluations`), and its readers (`rule`, `info`, `exceeded?`,
+`to_response_headers`) report the **most constraining** one: a blocking
+evaluation first, then exceeded ones, then the fewest requests remaining,
+ties broken by declaration order (the ranking is `Result::Evaluation#<=>`).
+That is what keeps `to_response_headers` honest — reporting any other matched
+rule would advertise headroom that a different rule is about to refuse:
+
+```
+per_ip    limit 1000  count  20  remaining 980
+per_user  limit  100  count  99  remaining   1   <- reported
+```
+
+An exceeded rule has `remaining` 0 and therefore outranks any rule still under
+its limit. For a `:log` rule that means shadow traffic surfaces to the caller
+as `exceeded? == true` (with `action` still `:allow`) — visible, but unable to
+block. A `:log`-only path that matches therefore returns `matched? == true`
+and its check is counted as `checks_total{matched="true"}`.
 
 ```mermaid
 flowchart TD
@@ -191,59 +252,162 @@ flowchart TD
     Iter -->|yes| Match{rule.match<br/>all satisfied?}
     Match -->|no| Iter
     Match -->|yes| Skip{rule.action<br/>== :skip?}
-    Skip -->|"yes (no Redis op)"| SkipEmit[Emit calls_total<br/>action=skip]
+    Skip -->|"yes (no Redis op)"| SkipEmit[Emit rule_evaluations_total<br/>action=skip, result=skip]
     SkipEmit --> SkipReturn([Return matched=true<br/>action=:allow])
-    Skip -->|no| 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]
+    Skip -->|no| Ban{"ban_for rule with<br/>a ban in force?"}
+    Ban -->|"yes (no increment)"| Build
+    Ban -->|no| Eval["INCR Redis counter<br/>(see Redis sequence below)"]
+    Eval --> Build[Build Evaluation<br/>resolve limit/period]
+    Build --> Add[Add evaluation to Result]
+    Add --> Emit[Emit rule_evaluations_total<br/>+ limit/period gauges]
+    Emit --> Act{"result.block?<br/>(:limit rule over its limit,<br/>or its ban in force)"}
+    Act -->|yes| Return([Return Result<br/>action=:block])
+    Act -->|"no (:log, or under limit)"| Iter
+    Iter -->|no more rules| Return2([Return Result reporting<br/>most-constraining evaluation,<br/>or matched=false if none])
+    Return --> Check[Emit checks_total<br/>action, matched, error]
+    SkipReturn --> Check
+    Return2 --> Check
+    Eval -. StandardError .-> Error[Emit errors_total +<br/>checks_total error=true<br/>log warn]
     Error --> ReturnErr([Return error=true<br/>action=:allow])
 ```
 
+Error handling is whole-check, not per-rule: a Redis failure part-way through
+discards the verdicts of the rules already evaluated, even though their counters
+were incremented. Those requests are counted but produce no verdict — the
+fail-open trade-off is that a request is never blocked on a partial evaluation.
+
+`rule_evaluations_total` is emitted **per evaluated rule** (including matched
+`:skip` rules); `checks_total` is emitted **exactly once per check**, whatever
+path the evaluation takes — so summing `checks_total` by `rate_limiter` counts
+requests through the limiter, and "no rule matched" is `matched="false"` on the
+check rather than a placeholder rule.
+
+Only matched rules are evaluated: a rule whose `match:` conditions are not
+satisfied emits nothing to `rule_evaluations_total` (match-testing is not an
+evaluation), so the counter has no "didn't match" population and needs no
+label for it. A matched `count_distinct` rule skipped by the missing-key
+fail-open also emits nothing here — it was never evaluated; that check is
+visible via `checks_total{error="true"}` and the
+`rate_limit_missing_count_distinct` log, which carries the rule name.
+
+During the transition the deprecated `calls_total` counter is additionally
+emitted at every point the diagram emits `rule_evaluations_total` (with its
+historical per-rule semantics, including the `rule="unmatched"` placeholder
+after the loop). It is not shown above to keep the diagram legible; see the
+Metrics table below.
+
 ### Actions
 
-The rule's `action` controls how the `Result` reports an over-limit hit. The
-counter is always incremented when a rule matches, except for `:skip` rules,
-which never touch Redis:
-
-- `: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.
+The rule's `action` describes what the rule does; the result's `action`
+describes the outcome — what the caller should do — and is only ever `:allow`
+or `:block`. A matching rule increments its counter, with two exceptions:
+`:skip` rules never touch Redis, and a rule carrying `ban_for` whose ban is
+already in force short-circuits before incrementing. The `result` label on
+`rule_evaluations_total` records what each evaluation decided:
+
+| rule action | what it does                                  | exceeded? | result action | `result` label | terminating?  |
+|-------------|-----------------------------------------------|-----------|---------------|----------------|---------------|
+| `:limit`    | count against the limit                       | no        | `:allow`      | `allow`        | no — continue |
+| `:limit`    | count against the limit                       | yes       | `:block`      | `block`        | yes — stop    |
+| `:log`      | count against the limit (observability only)  | no        | `:allow`      | `allow`        | no — continue |
+| `:log`      | count against the limit (observability only)  | yes       | `:allow`      | `log`          | no — continue |
+| `:skip`     | don't count (bypass)                          | n/a       | `:allow`      | `skip`         | yes — stop    |
+
+A rule may also carry `ban_for`, which changes the accounting rather than the
+action. On crossing the limit it writes a ban that outlives the counting
+window, and it stops counting while that ban holds:
+
+| rule action | with `ban_for`                                | exceeded? | result action | `result` label | terminating?  |
+|-------------|-----------------------------------------------|-----------|---------------|----------------|---------------|
+| `:limit`    | count, or skip counting while banned          | yes       | `:block`      | `banned`       | yes — stop    |
+| `:log`      | same accounting, records what it would do     | yes       | `:allow`      | `banned`       | no — continue |
+
+- `:limit` — when exceeded, `Result#action` is `:block` and evaluation
+  terminates. Caller should reject the request (e.g. with HTTP 429). When under
+  the limit, evaluation continues to the next rule.
+- `:log` — **never terminating and never blocking**. The rule counts the
+  request and records metrics, but evaluation always continues to the next
+  rule. This is the mechanism for shadow rules during rollout: stack a `:log`
+  rule and a `:limit` rule together and the `:log` rule cannot disable the
+  `:limit` rule. When exceeded, a `:log` rule can still be the rule reported in
+  the `Result` (`exceeded? == true`, `action == :allow`) if nothing more
+  constraining matched.
 - `:skip` — bypass. A matching rule terminates evaluation with
   `Result#action` `:allow` **without any Redis operation**: nothing is
   counted, so `limit`, `period`, `characteristics`, and `count_distinct` are
   inert and the result carries no `info` (`to_response_headers` is `{}`).
-  The match is still observable via `calls_total{action="skip"}`. Use this
-  for bypasses that don't need a counter; use `:allow` only when you want
-  the bypassed traffic counted.
+  The match is still observable via `rule_evaluations_total{action="skip"}`.
+  Use this for bypasses.
+- `ban_for` — enforcement that outlives the window, on either counting action.
+  On crossing the limit the rule writes a second key that keeps blocking for
+  `ban_for` seconds, long after the counter window has expired. While that ban
+  is in force the rule reports `exceeded? == true` and does not count, so a
+  caller cannot extend its own ban, and `reset_at` reports when the ban lifts
+  rather than when the window rolls. Use this where repeated failures should
+  cost more than a window, such as authentication attempts. State can be
+  discarded early with [`#clear`](#clearing-state).
+
+  With `action: :limit` the ban blocks. With `action: :log` the rule does all
+  of the same accounting, including writing the ban and suppressing counting
+  while it holds, and only skips the blocking, so a shadow measures what
+  enforcement would have produced rather than approximating it.
+
+  A `ban_for` shorter than `period` is legal but surprising: the ban can lapse
+  while the counter is still over the limit, so `peek` reports not-exceeded
+  while the next `check` re-bans immediately. Bans are normally longer than the
+  window they are counted in.
+
+  The duration is whole seconds and must be at least 1, since the ban is
+  written with `SET EX`. A callable is checked again each time it resolves, and
+  a value under a second raises rather than reaching Redis. Being an error, it
+  fails open like any other, so a rule whose `ban_for` cannot resolve stops
+  blocking entirely: watch `errors_total` after changing one.
+
+  Take care combining `ban_for` with `cost:`. One expensive call can cross the
+  limit on its own, and with a ban attached that costs the caller the whole ban
+  rather than a single rejection. Checking with `peek` first has the same edge,
+  since the call it deliberately lets through is enough to start a ban. Bans
+  suit counting discrete failures, such as bad credentials, better than they
+  suit variable-cost resource limits.
 
 ### Redis keys
 
 Each matched check writes a key shaped:
 
 ```
-labkit:rl:<limiter_name>:<rule_name>:<char>:<value>[:<char>:<value>...]
+labkit:rl:{<limiter_name>:<rule_name>:<char>:<value>[:<char>:<value>...]}
 ```
 
+The braces are a Redis [hash tag](https://redis.io/docs/latest/operate/oss_and_stack/reference/cluster-spec/#hash-tags):
+on a Redis Cluster only the braced part decides the slot, so every key for one
+rule and identifier lands on the same shard. `BAN_SCRIPT` touches two keys in
+one call, and a cluster rejects a script whose keys span slots.
+
 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.
+encoded as `_unknown_`. The TTL is set on the first write of each window and
+is not extended on subsequent increments, so the window is a true fixed
+window starting at the first request, not a sliding window.
+
+A check is a single `EVALSHA` of `INCR_SCRIPT` (or `SADD_SCRIPT` for
+`count_distinct` rules, or `BAN_SCRIPT` for rules carrying `ban_for`). Doing the whole
+read-modify-write inside Lua means there is no window between the increment
+and the `EXPIRE` in which a key could be left without a TTL.
+
+A rule carrying `ban_for` writes a second key alongside its counter, sharing the
+same hash tag and carrying its own `ban_for` TTL:
+
+```
+labkit:rl:{<limiter_name>:<rule_name>:<char>:<value>[:<char>:<value>...]}:ban
+```
+
+The suffix sits outside the tag, so it cannot change the slot and cannot
+collide with a characteristic value, and both keys are found by the same
+`labkit:rl:{<limiter>:<rule>*` glob. The ban key outlives its counter by
+design: that is the whole point of `ban_for`.
+`BAN_SCRIPT` checks the ban before incrementing, so the ban check,
+the increment and the ban write are one atomic operation and a concurrent
+check cannot miss the threshold crossing.
 
 ```mermaid
 sequenceDiagram
@@ -251,36 +415,51 @@ sequenceDiagram
     participant E as Evaluator
     participant P as Connection pool
     participant R as Redis
+    participant L as INCR_SCRIPT (Lua)
 
     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.
+    E->>R: EVALSHA INCR_SCRIPT key, [period, cost]
+    R->>L: run script
+    L->>L: INCRBYFLOAT key cost
+    L->>L: TTL key
+    alt TTL < 0 (key was missing, or had no expiry)
+        L->>L: EXPIRE key period
+        Note over L: Returns period as the TTL:<br/>the window starts now.
+    else TTL >= 0 (window already running)
+        Note over L: TTL is not extended:<br/>fixed window from first write.
     end
+    L-->>R: {count, ttl}
+    R-->>E: [count, ttl]
     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.
+Because `INCRBYFLOAT` preserves an existing key's TTL, and creates a missing
+key with no expiry, the TTL only needs reading once — after the increment.
+That single read distinguishes both cases the script must handle, so there is
+no reason to read it again before mutating.
+
+`peek` does not use a script: it pipelines `GET` + `TTL` (or `SCARD` + `TTL`)
+and never issues `EXPIRE`, so it cannot start or extend a window. A missing
+key (`GET → nil`, `TTL → -2`) is reported as `count = 0`, and `build_evaluation`
+falls back to the rule's period for `reset_at` since there is no Redis-side
+window to read.
 
 ## Result
 
-`Result` carries the decision back to the caller:
+`Result` carries the decision back to the caller. It collects one
+`Result::Evaluation` per counted rule; `rule`, `exceeded?`, and `info` report
+the most constraining one (see [Evaluation flow](#evaluation-flow)):
 
 ```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.exceeded?          # => true if the reported rule's counter > limit
+result.action             # => :block | :allow — what the caller should do
+result.block?             # => result.action == :block
+result.rule               # => the reported Rule, or nil
 result.error?             # => true if Redis failed (see Fail-open)
 result.info               # => Result::Info or nil
+result.evaluations        # => every counted Result::Evaluation, in rule order
 result.to_response_headers
 # => { "RateLimit-Limit" => "...", "RateLimit-Remaining" => "...", "RateLimit-Reset" => "<unix-ts>" }
 ```
@@ -302,27 +481,53 @@ safe to merge unconditionally.
 
 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
+logged at WARN with `error_type: "rate_limit_error"` and returned as an error
+`Result` (`matched?` false, `error?` true, `action` `:allow`). The caller
 should treat the request as allowed.
 
+A failed-open `check` is still counted: it emits
+`checks_total{action="allow", matched="false", error="true"}`, so the fraction
+of checks that encountered an error is `checks_total{error="true"}` over
+`checks_total`. `error="true"` also covers a check where a matched
+`count_distinct` rule was skipped because the identifier was missing its
+`count_distinct` key — that check completes (`action` and `matched` describe
+its outcome as usual), so `error="true"` is not exclusively fail-open traffic.
+
+The deprecated `gitlab_labkit_rate_limiter_errors_total` counter is still
+incremented on every fail-open (whole-check and per-rule `count_distinct`),
+and remains the only error metric for `peek`, which emits no `checks_total`
+(peek must not inflate the per-check counter). The follow-up MR that removes
+`errors_total` must first decide where `peek` errors go — a dedicated peek
+metric, or logs only.
+
+Metric emission itself is best-effort: a failure in the metrics stack never
+alters the verdict or breaks fail-open, and is logged at WARN with
+`error_type: "rate_limit_metrics_error"` (once per process, to avoid
+flooding).
+
 ## 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"`, `"skip"`. `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).
+| metric                                              | type    | labels                                       | meaning                                                              |
+|-----------------------------------------------------|---------|----------------------------------------------|----------------------------------------------------------------------|
+| `gitlab_labkit_rate_limiter_checks_total`           | counter | `rate_limiter`, `action`, `matched`, `error` | Exactly one increment per `check` call, including fail-open. `action` is what the caller should do (`"allow"` or `"block"`); `matched` and `error` are `"true"`/`"false"`. |
+| `gitlab_labkit_rate_limiter_rule_evaluations_total` | counter | `rate_limiter`, `rule`, `action`, `result`   | One increment per evaluated rule (plus one per matched `:skip` rule). `action` is the configured rule action (`"limit"`, `"log"`, `"skip"`); `result` is what the evaluation decided (`"allow"`, `"block"`, `"log"`, `"skip"`, `"banned"` — see the Actions table). |
+| `gitlab_labkit_rate_limiter_calls_total`            | counter | `rate_limiter`, `rule`, `action`             | **Deprecated** — superseded by `checks_total` + `rule_evaluations_total`. Historical per-rule counter: one increment per counted rule (plus one per matched `:skip` rule), `rule="unmatched", action="allow"` when no rule matched. Emitted unchanged during the transition. |
+| `gitlab_labkit_rate_limiter_errors_total`           | counter | `rate_limiter`                               | **Deprecated** — use `checks_total{error="true"}`. Fail-open events (any `StandardError` in the labkit path); still the only error metric for `peek`. |
+| `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.                                   |
+
+`sum by (rate_limiter) (rate(gitlab_labkit_rate_limiter_checks_total[5m]))` is
+the request rate through a limiter — no exclusions or dedup needed. A single
+`check` call emits **one** `checks_total` increment and as many
+`rule_evaluations_total` increments as rules it evaluated (possibly zero).
+
+**Transition:** the deprecated `calls_total` and `errors_total` counters keep
+emitting exactly as before this split, so existing dashboards and alerts stay
+correct while consumers migrate to the new counters. Both are removed in a
+follow-up major release once nothing consumes them.
 
 ## Dev/test vs production guards