gitlab-labkit 2.8.1 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ad3bb9ba369010544041c2ab2d2ec2d8610c535c5b2c5e592fe0e8313c56a66
-  data.tar.gz: 4fa90bdb331f44920cc9969603db7189e42dec21c7fab1d7593e91455de323c3
+  metadata.gz: 5fbd752b05c1341ef1292c7a3a1ae3555dd27230d7afc830e0c713547bdd02ee
+  data.tar.gz: 6dc8eab0332b9b6851627fe83a95bfb0bacefbe3222d712e28a8e210c19fdb8a
 SHA512:
-  metadata.gz: 21c914360a54bb30e914e7b6771781657463b3febd83b81634b88513f2986d7d9f25016bae84781b69918429a49c13fdfdf7da8581d385bc13adb698c8728f1d
-  data.tar.gz: e8b1b9f46c438e2608a1f12e55d2fd3f518586795dfb0327b08fed8bcd6496525fb0fba71c5212fdab45b45a3ca1b3b9c792dc212a838a98124be37d698fd823
+  metadata.gz: 56316fcea7b575a62119a814f3e3b4c85dc8d5e93ed72e2316bd47388bd142dd44ae21f07f2b6f40d070573c04bf6b79c26e14601f90e0a2f6fcf263fa05ce36
+  data.tar.gz: 65e7e06919637356e25ab5d6f56880df2eb7e340474afeaf01212fe55612439d8bba8707d2d1bc835c864723cd0d15cca135065756ce3f17a9bd959f253775f3

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
@@ -146,7 +146,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`, `:allow`, `:skip`. Default `:block`. See [Actions](#actions).                           |
+| `action`          | What the result reports when the limit is exceeded. One of `:block`, `:log`, `:skip`. 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
@@ -198,7 +198,7 @@ flowchart TD
     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])
+    Act -->|:block| 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]
@@ -219,17 +219,12 @@ which never touch Redis:
   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.
 - `: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.
+  for bypasses.
 
 ### Redis keys
 
@@ -241,9 +236,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
@@ -251,24 +251,35 @@ 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_result`
+falls back to the rule's period for `reset_at` since there is no Redis-side
+window to read.
 
 ## Result
 

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:)
@@ -247,7 +249,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

data/lib/labkit/rate_limit/result.rb

@@ -8,9 +8,9 @@ module Labkit
     # 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 allow,
-    #                      rule configured to skip (bypass, nothing counted),
-    #                      no rule matched, or error (fail-open)
+    #             :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)

data/lib/labkit/rate_limit/rule.rb

@@ -2,7 +2,7 @@
 
 module Labkit
   module RateLimit
-    KNOWN_ACTIONS = %i[block log allow skip].freeze
+    KNOWN_ACTIONS = %i[block log skip].freeze
     RULE_NAME_PATTERN = /\A[a-z0-9_]+\z/
     RULE_NAME_MAX_LENGTH = 64
 
@@ -13,9 +13,7 @@ module Labkit
     # 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), :allow
-    #                   (count but always permit; terminates evaluation on match
-    #                   regardless of whether the limit was exceeded), or :skip
+    #                   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)

metadata

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