gitlab-labkit 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c4b2288dc9341d5acd02a9ad274702ad2c44793c5760f04b6597c7404cad509
-  data.tar.gz: f6bc276c4452b9952dcd5e194f76d74c787ba122ae39070d35fc507aec06d444
+  metadata.gz: c872947164d25ef7f75203c6195fe04bbc8c9002639d59fadf10672d47201862
+  data.tar.gz: d0308016fd538669e466d2e499aa283d47e82bb4d53bd530c07bce74162b16b4
 SHA512:
-  metadata.gz: fb5d89354c732b5ea0ac8579422a2fd3212e2e79f9d035ad0bdb642258710e2c7cf43abbfbd9c6b6f95d4fe190799ddbbcaf34b0b3d51ff857c0a8330e56af7f
-  data.tar.gz: cea073f528c655e9df4df9715a6a7a5728f13c55e75190f2ace56ca15aba59ec84ac902037125b54de0f7631fbcd03120fd1a8caad3d8854481d39a73eeb11d6
+  metadata.gz: e6cb4000c77a3ebe764b61e0d536db95dbe3c79378a1d95744747e7eff2509cb435561eba2963ae83107eea37364f5515e3a64bd9491c799c2b9508c9293c793
+  data.tar.gz: 64cc36f40cb6140b09fc54d873a102098a7fe05b2e967960317c782dc53b224c513fe676e6435dae48b6b0fc33e9e95dd8f32f10230900dea809bbef8bdd03e0

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,11 @@ 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`.
 
 ## Identifier
 
@@ -146,7 +148,7 @@ 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`, `: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.                                           |
 
 Making `limit` or `period` callable is the supported pattern for
@@ -180,10 +182,37 @@ 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 emits no `rule="unmatched"` metric.
 
 ```mermaid
 flowchart TD
@@ -194,31 +223,53 @@ flowchart TD
     Skip -->|"yes (no Redis op)"| SkipEmit[Emit calls_total<br/>action=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| Return([Return Result])
-    Iter -->|no more rules| Unmatched[Emit calls_total<br/>rule=unmatched, action=allow]
+    Eval --> Build[Build Evaluation<br/>resolve limit/period]
+    Build --> Add[Add evaluation to Result]
+    Add --> Emit[Emit calls_total + limit/period gauges]
+    Emit --> Act{"result.block?<br/>(:limit rule over limit)"}
+    Act -->|yes| Return([Return Result<br/>action=:block])
+    Act -->|"no (:log, or :limit under limit)"| Iter
+    Iter -->|no more rules| Any{any rule<br/>evaluated?}
+    Any -->|yes| ReturnFold([Return Result reporting<br/>most-constraining evaluation])
+    Any -->|no| 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])
 ```
 
+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.
+
+Note that `calls_total` is emitted **per matched rule**, so summing it by
+`rate_limiter` counts rule evaluations, not requests.
+
 ### 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.
+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`. The counter is always incremented when a rule matches, except for
+`:skip` rules, which never touch Redis:
+
+| rule action | what it does                                  | exceeded? | result action | terminating?  |
+|-------------|-----------------------------------------------|-----------|---------------|---------------|
+| `:limit`    | count against the limit                       | no        | `:allow`      | no — continue |
+| `:limit`    | count against the limit                       | yes       | `:block`      | yes — stop    |
+| `:log`      | count against the limit (observability only)  | no        | `:allow`      | no — continue |
+| `:log`      | count against the limit (observability only)  | yes       | `:allow`      | no — continue |
+| `:skip`     | don't count (bypass)                          | n/a       | `:allow`      | yes — stop    |
+
+- `: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
@@ -236,9 +287,14 @@ 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.
+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). 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.
 
 ```mermaid
 sequenceDiagram
@@ -246,36 +302,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>" }
 ```
@@ -297,8 +368,8 @@ 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
+logged at WARN with `message: "rate_limit_error"` and returned as an error
+`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.
 
@@ -309,15 +380,14 @@ should treat the request as allowed.
 
 | 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_calls_total`        | counter | `rate_limiter`, `rule`, `action`    | One increment per counted rule (plus one per matched `:skip` rule). `action` is the rule-level outcome: `"allow"` (under limit), `"limit"` (blocking `:limit` rule), `"log"` (exceeded `:log` rule), `"skip"`. `rule="unmatched", action="allow"` when no rule matched. |
 | `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).
+Because every matching rule is counted, a single `check` call can emit
+**multiple** `calls_total` increments: one per counted rule (or a single
+`rule="unmatched"` increment if nothing matched).
 
 ## Dev/test vs production guards
 

data/lib/labkit/rate_limit/evaluator.rb

@@ -22,40 +22,42 @@ module Labkit
       # Redis treats the result as a no-op on the stored value while
       # still observing the post-state count and TTL we return.
       #
-      # ttl_before < 0 covers TTL=-2 (key missing) and TTL=-1 (no expiry).
+      # ttl_after < 0 covers TTL=-2 (key missing) and TTL=-1 (no expiry).
       # The -1 case shouldn't arise with the atomic script, but self-healing
       # recovers keys left without TTL by any prior bug.
       INCR_SCRIPT = Labkit::Redis::Script.new(<<~LUA)
         local ttl = ARGV[1]
         local cost = tonumber(ARGV[2])
-        local ttl_before = redis.call('TTL', KEYS[1])
 
         local count = redis.call('INCRBYFLOAT', KEYS[1], cost)
-        if ttl_before < 0 then
+        local ttl_after = redis.call('TTL', KEYS[1])
+        if ttl_after < 0 then
           redis.call('EXPIRE', KEYS[1], ttl)
+          ttl_after = tonumber(ttl)
         end
 
-        return {count, redis.call('TTL', KEYS[1])}
+        return {count, ttl_after}
       LUA
 
       # Atomic SADD + SCARD + conditional EXPIRE. SET-cardinality counterpart
-      # of INCR_SCRIPT; same shape (read TTL, mutate, set TTL when missing,
+      # of INCR_SCRIPT; same shape (mutate, read TTL, set TTL when missing,
       # return post-state {count, TTL}). count is SCARD, not the SADD return.
       #
-      # ttl_before < 0 covers TTL=-2 (key missing) and TTL=-1 (no expiry),
+      # ttl_after < 0 covers TTL=-2 (key missing) and TTL=-1 (no expiry),
       # so this also self-heals orphan keys left without TTL.
       SADD_SCRIPT = Labkit::Redis::Script.new(<<~LUA)
         local ttl = ARGV[1]
         local member = ARGV[2]
-        local ttl_before = redis.call('TTL', KEYS[1])
 
         redis.call('SADD', KEYS[1], member)
         local count = redis.call('SCARD', KEYS[1])
-        if ttl_before < 0 then
+        local ttl_after = redis.call('TTL', KEYS[1])
+        if ttl_after < 0 then
           redis.call('EXPIRE', KEYS[1], ttl)
+          ttl_after = tonumber(ttl)
         end
 
-        return {count, redis.call('TTL', KEYS[1])}
+        return {count, ttl_after}
       LUA
 
       def initialize(name:, rules:, redis:, logger:)
@@ -72,7 +74,7 @@ module Labkit
         # timeout, OOM) not only Redis protocol errors.
         report_error_metrics
         log_error(e, identifier)
-        Result.new(matched: false, error: true, action: :allow)
+        Result.error
       end
 
       # Read-without-increment counterpart to {#check}. Same matching and Result
@@ -83,30 +85,48 @@ module Labkit
       rescue StandardError => e
         report_error_metrics
         log_error(e, identifier)
-        Result.new(matched: false, error: true, action: :allow)
+        Result.error
       end
 
       private
 
-      # :log rules are non-terminating: they emit metrics and continue,
-      # so a shadow :log rule cannot disable a following :block rule.
+      # Every rule that matches is evaluated and counted; matching does not
+      # short-circuit the loop. Exactly two cases terminate it early:
       #
-      # :skip rules terminate on match without touching Redis: no counter is
-      # incremented, so the branch sits before the count_distinct check
-      # (identifier completeness is irrelevant to a rule that builds no key).
-      # calls_total still increments so the bypass stays observable.
+      # - :skip terminates on match without touching Redis. No counter is
+      #   incremented, so the branch sits before the count_distinct check
+      #   (identifier completeness is irrelevant to a rule that builds no key).
+      #   calls_total still increments so the bypass stays observable.
+      # - a :limit rule over its limit terminates, because the request is
+      #   rejected and later rules cannot change that. Rules declared after it
+      #   are neither counted nor evaluated, so a blocked request debits every
+      #   rule up to and including the one that blocked, and none after it.
+      #
+      # Every other matched rule - :log, and :limit while under its limit - is
+      # counted and collected into the returned Result, which reports the
+      # most-constraining evaluation (ranking lives in Result::Evaluation#<=>).
+      # cost is therefore debited from every matching rule, not just the first.
       #
       # SET-mode rules (rule.count_distinct set) that match but whose identifier
       # is missing the count_distinct key fail open + log + bump errors_total, and
       # the loop continues to the next rule (the rule is treated as not applicable
       # rather than aborting the whole evaluation).
+      #
+      # Error handling stays whole-check (see #check): a raise part-way through
+      # discards the results of the rules already evaluated, even though their
+      # 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)
+        result = Result.new
+
         @rules.each do |rule|
           next unless rule_matches?(rule, identifier)
 
           if rule.action == :skip
             report_skipped_metrics(rule)
-            return skip_result(rule)
+            return result.skip!(rule)
           end
 
           if rule.count_distinct && missing_count_distinct_value?(rule, identifier)
@@ -115,44 +135,42 @@ module Labkit
             next
           end
 
-          result = evaluate_rule(rule, identifier, cost, rule_context)
-          report_matched_metrics(result)
-          return result unless rule.action == :log
+          evaluation = evaluate_rule(rule, identifier, cost, rule_context)
+          result.add_evaluation(evaluation)
+          report_matched_metrics(evaluation)
+          return result if result.block?
         end
 
-        report_unmatched_metrics
-        Result.new(matched: false, action: :allow)
+        report_unmatched_metrics unless result.matched?
+        result
       end
 
-      # Mirror of check_rules without metrics: peek skips :log rules (their state
-      # is unobservable through peek).
+      # Mirror of check_rules without metrics or writes. :log rules are read
+      # here too: check can report a :log rule's evaluation, so excluding them
+      # would make peek answer a different question than check.
       #
       # 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)
+        result = Result.new
+
         @rules.each do |rule|
-          next if rule.action == :log
           next unless rule_matches?(rule, identifier)
 
-          return skip_result(rule) if rule.action == :skip
+          return result.skip!(rule) if rule.action == :skip
 
-          return peek_rule(rule, identifier, rule_context)
+          result.add_evaluation(peek_rule(rule, identifier, rule_context))
+          return result if result.block?
         end
 
-        Result.new(matched: false, action: :allow)
+        result
       end
 
       def rule_matches?(rule, identifier)
         rule.match.all? { |key, matcher| matcher.match?(identifier[key]) }
       end
 
-      # A matched :skip rule allows without evaluating: no counter exists, so
-      # info is nil (to_response_headers is {} for skip results).
-      def skip_result(rule)
-        Result.new(matched: true, action: :allow, rule: rule)
-      end
-
       def missing_count_distinct_value?(rule, identifier)
         value = identifier[rule.count_distinct]
         value.nil? || value.to_s.empty?
@@ -172,7 +190,7 @@ module Labkit
             incr_with_ttl(redis_key, resolved_period, cost)
           end
 
-        build_result(rule, resolved_limit, resolved_period, count, ttl)
+        build_evaluation(rule, resolved_limit, resolved_period, count, ttl)
       end
 
       def peek_rule(rule, identifier, rule_context)
@@ -181,12 +199,10 @@ module Labkit
         resolved_period = Integer(resolve_value(rule.period, rule_context))
 
         count, ttl = rule.count_distinct ? scard_with_ttl(redis_key) : read_with_ttl(redis_key)
-        build_result(rule, resolved_limit, resolved_period, count, ttl)
+        build_evaluation(rule, resolved_limit, resolved_period, count, ttl)
       end
 
-      def build_result(rule, resolved_limit, resolved_period, count, ttl)
-        exceeded = count > resolved_limit
-        action = exceeded ? rule.action : :allow
+      def build_evaluation(rule, resolved_limit, resolved_period, count, ttl)
         info = Result::Info.new(
           resolved_limit: resolved_limit, resolved_period: resolved_period,
           count: count,
@@ -194,7 +210,7 @@ module Labkit
           reset_at: Time.now.utc + (ttl >= 0 ? ttl : resolved_period)
         )
 
-        Result.new(matched: true, exceeded: exceeded, action: action, rule: rule, info: info)
+        Result::Evaluation.new(rule: rule, exceeded: count > resolved_limit, info: info)
       end
 
       def build_redis_key(rule, identifier)
@@ -247,7 +263,7 @@ module Labkit
       end
 
       # Atomically increments the counter by `cost`, sets the TTL on first
-      # write, and reads back the post-increment TTL, all in one Redis
+      # write, and returns the window's remaining TTL, all in one Redis
       # operation via Lua. See INCR_SCRIPT for the script body.
       #
       # count is parsed as Float because INCRBYFLOAT returns a string-encoded
@@ -262,7 +278,7 @@ module Labkit
 
       # Pipelined GET + TTL. No EXPIRE: peek must not extend the window.
       # A missing key (GET => nil, TTL => -2) is reported as count=0; the
-      # build_result fallback then derives reset_at from the rule period
+      # build_evaluation fallback then derives reset_at from the rule period
       # since there is no Redis-side window to read.
       #
       # Float parsing accepts both INCR-stored ("5") and INCRBYFLOAT-stored
@@ -323,19 +339,19 @@ module Labkit
         )
       end
 
-      def report_matched_metrics(result)
+      def report_matched_metrics(evaluation)
         Metrics.calls_total.increment(
           rate_limiter: @name,
-          rule: result.rule.name,
-          action: result.action.to_s
+          rule: evaluation.rule.name,
+          action: (evaluation.exceeded? ? evaluation.rule.action : :allow).to_s
         )
         Metrics.limit_gauge.set(
-          { rate_limiter: @name, rule: result.rule.name },
-          result.info.resolved_limit
+          { rate_limiter: @name, rule: evaluation.rule.name },
+          evaluation.info.resolved_limit
         )
         Metrics.period_gauge.set(
-          { rate_limiter: @name, rule: result.rule.name },
-          result.info.resolved_period
+          { rate_limiter: @name, rule: evaluation.rule.name },
+          evaluation.info.resolved_period
         )
       end
 

data/lib/labkit/rate_limit/limiter.rb

@@ -15,7 +15,7 @@ module Labkit
     #     rules: [Labkit::RateLimit::Rule.new(name: "api_user", limit: 100, period: 60, characteristics: [:user])]
     #   )
     #   result = limiter.check({ user: 42, ip: "1.2.3.4" })
-    #   render_429 if result.exceeded? && result.action == :block
+    #   render_429 if result.action == :block
     class Limiter
       NAME_PATTERN = /\A[a-z0-9_]+\z/
 

data/lib/labkit/rate_limit/metrics.rb

@@ -5,9 +5,10 @@ module Labkit
     module Metrics
       module_function
 
-      # :log rules are non-terminating: a check that matched only :log rules
-      # increments calls_total once per matched :log rule AND once with
-      # rule="unmatched", action="allow", since no terminating decision was made.
+      # Emitted once per *matched rule*, not once per check: every rule that
+      # matches is evaluated, so summing this by rate_limiter counts rule
+      # evaluations rather than requests. rule="unmatched", action="allow" is
+      # emitted only when no rule matched at all.
       def calls_total
         Labkit::Metrics::Client.counter(
           :gitlab_labkit_rate_limiter_calls_total,

data/lib/labkit/rate_limit/result.rb

@@ -3,34 +3,100 @@
 module Labkit
   module RateLimit
     # Result is the return value of Limiter#check.
-    # matched?  - true if a rule's match conditions were satisfied
-    # exceeded? - true if the matched rule's counter exceeded its limit
-    # action    - the outcome: what the caller should do
-    #             :block = rule matched, exceeded, rule configured to block
-    #             :log   = rule matched, exceeded, rule configured to log only
-    #             :allow = rule matched but count within limit, rule configured
-    #                      to skip (bypass, nothing counted), no rule matched,
-    #                      or error (fail-open)
-    #             The rule's configured action is available via rule.action.
-    # rule      - the matched Rule object (nil when matched? is false)
-    # error?    - true if Redis was unavailable; result fails open (exceeded? is false)
-    # info      - Result::Info with per-window counters; nil when matched? is false,
-    #             error?, or the matched rule is :skip (no counter exists)
-    Result = Data.define(:matched, :exceeded, :action, :rule, :error, :info) do
-      def initialize(matched:, action: nil, exceeded: false, rule: nil, error: false, info: nil)
-        super
+    #
+    # It accumulates one Result::Evaluation per matched-and-counted rule; the
+    # reader methods report the single most-constraining evaluation (see
+    # #most_constraining). A matched :skip rule or a fail-open error replaces
+    # the evaluations as the source of the reported outcome.
+    #
+    # Result is a mutable accumulator, not a value object: two Results built
+    # from the same evaluations are not #==.
+    #
+    # matched?    - true if at least one rule's match conditions were satisfied
+    # exceeded?   - true if the reported evaluation's counter exceeded its limit
+    # action      - the outcome: what the caller should do
+    #               :block = a :limit rule matched and is over its limit
+    #               :allow = everything else, including an exceeded :log rule
+    #               (visible via exceeded?), a matched :skip rule, no rule
+    #               matched, and error (fail-open).
+    #               The rule's configured action is available via rule.action.
+    # rule        - the reported Rule: the :skip rule when one matched, otherwise
+    #               the most-constraining evaluated Rule (nil when matched? is
+    #               false). Other rules may also have matched and been counted;
+    #               see #evaluations.
+    # error?      - true if Redis was unavailable; result fails open (exceeded? is false)
+    # info        - Result::Info with per-window counters for the reported rule;
+    #               nil when matched? is false, error?, or the matched rule is
+    #               :skip (no counter exists)
+    # evaluations - every counted evaluation, in rule declaration order
+    class Result
+      attr_reader :evaluations
+
+      def self.error
+        new(error: true)
+      end
+
+      def initialize(error: false)
+        @evaluations = []
+        @skip_rule = nil
+        @error = error
+        @most_constraining = nil
+      end
+
+      def add_evaluation(evaluation)
+        @most_constraining = nil
+        @evaluations << evaluation
+        self
+      end
+
+      # Records a matched :skip rule: the request is allowed and the skip rule
+      # is the one reported, regardless of any evaluations already collected.
+      def skip!(rule)
+        @skip_rule = rule
+        self
       end
 
       def matched?
-        matched
+        skipped? || @evaluations.any?
+      end
+
+      def skipped?
+        !!@skip_rule
+      end
+
+      def block?
+        !skipped? && @evaluations.any?(&:block?)
       end
 
       def exceeded?
-        exceeded
+        return false if skipped?
+
+        !most_constraining.nil? && most_constraining.exceeded?
       end
 
       def error?
-        error
+        @error
+      end
+
+      def action
+        block? ? :block : :allow
+      end
+
+      def rule
+        @skip_rule || most_constraining&.rule
+      end
+
+      def info
+        return nil if skipped?
+
+        most_constraining&.info
+      end
+
+      # The evaluation with the strongest claim on the outcome; ties keep the
+      # earliest-declared rule (min returns the first of tied elements).
+      # Memoized; add_evaluation invalidates.
+      def most_constraining
+        @most_constraining ||= @evaluations.min
       end
 
       # Returns RFC-compliant rate limit response headers, or {} when no rule matched or an error occurred.
@@ -48,6 +114,39 @@ module Labkit
       end
     end
 
+    # The outcome of counting one matched rule.
+    # rule     - the evaluated Rule
+    # exceeded - whether the post-increment count exceeded the resolved limit
+    # info     - Result::Info with the per-window counters
+    #
+    # Evaluations order by constraint: a blocking evaluation (:limit rule over
+    # its limit) ranks strictly first - it decides the request no matter what
+    # any other rule reports - then exceeded ones, then fewest remaining.
+    # remaining floors at 0, so an exceeded :log rule ties with one sitting
+    # exactly on its limit; ranking exceeded ahead keeps a breach from being
+    # hidden by a rule that merely reached its limit.
+    Result::Evaluation = Data.define(:rule, :exceeded, :info) do
+      include Comparable
+
+      def exceeded?
+        exceeded
+      end
+
+      def block?
+        exceeded? && rule.action == :limit
+      end
+
+      def <=>(other)
+        constraint_rank <=> other.constraint_rank
+      end
+
+      protected
+
+      def constraint_rank
+        [block? ? 0 : 1, exceeded? ? 0 : 1, info.remaining]
+      end
+    end
+
     # Per-window counter data attached to a matched Result.
     # resolved_limit  - the evaluated limit Integer for this rule
     # resolved_period - the evaluated period Integer (seconds) for this rule

data/lib/labkit/rate_limit/rule.rb

@@ -2,7 +2,7 @@
 
 module Labkit
   module RateLimit
-    KNOWN_ACTIONS = %i[block log skip].freeze
+    KNOWN_ACTIONS = %i[limit log skip].freeze
     RULE_NAME_PATTERN = /\A[a-z0-9_]+\z/
     RULE_NAME_MAX_LENGTH = 64
 
@@ -12,11 +12,12 @@ module Labkit
     #                   the rule to apply; empty hash matches any identifier
     # limit           - request threshold; may be a callable (resolved per check)
     # 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 :skip
-    #                   (bypass: permit and terminate evaluation on match without
-    #                   counting; performs no Redis operation, so limit, period,
-    #                   characteristics, and count_distinct are inert)
+    # action          - :limit (enforce; the result blocks when the rule is over
+    #                   its limit, which also terminates evaluation), :log (count
+    #                   and log only, never blocks and never terminates), or
+    #                   :skip (bypass: permit and terminate evaluation on match
+    #                   without counting; performs no Redis operation, so limit,
+    #                   period, characteristics, and count_distinct are inert)
     # characteristics - identifier keys used to build the compound Redis counter key
     # count_distinct  - optional Symbol naming an identifier key. When set, the rule
     #                   counts the number of distinct values seen for that key within
@@ -43,7 +44,7 @@ module Labkit
         sym
       end
 
-      def initialize(name:, limit:, period:, characteristics:, match: {}, action: :block, count_distinct: nil)
+      def initialize(name:, limit:, period:, characteristics:, match: {}, action: :limit, count_distinct: nil)
         raise ArgumentError, "name must be a String or Symbol, got #{name.class}" unless name.is_a?(String) || name.is_a?(Symbol)
 
         name_str = name.to_s

data/lib/labkit/rate_limit.rb

@@ -40,7 +40,8 @@ module Labkit
       #
       # @param name [String] call site name
       # @param identifier [Identifier, Hash] caller attributes
-      # @param rules [Array<Rule>] ordered list of rules (first match wins)
+      # @param rules [Array<Rule>] ordered list of rules; every matching rule is
+      #   counted, and the Result reports the most constraining one
       # @param redis [Object, nil] Redis client; falls back to config.redis
       # @param logger [Logger, nil] logger; falls back to config.logger
       # @param cost [Numeric] amount to add to the counter; see Limiter#check

metadata

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