gitlab-labkit 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c4b2288dc9341d5acd02a9ad274702ad2c44793c5760f04b6597c7404cad509
-  data.tar.gz: f6bc276c4452b9952dcd5e194f76d74c787ba122ae39070d35fc507aec06d444
+  metadata.gz: 5fbd752b05c1341ef1292c7a3a1ae3555dd27230d7afc830e0c713547bdd02ee
+  data.tar.gz: 6dc8eab0332b9b6851627fe83a95bfb0bacefbe3222d712e28a8e210c19fdb8a
 SHA512:
-  metadata.gz: fb5d89354c732b5ea0ac8579422a2fd3212e2e79f9d035ad0bdb642258710e2c7cf43abbfbd9c6b6f95d4fe190799ddbbcaf34b0b3d51ff857c0a8330e56af7f
-  data.tar.gz: cea073f528c655e9df4df9715a6a7a5728f13c55e75190f2ace56ca15aba59ec84ac902037125b54de0f7631fbcd03120fd1a8caad3d8854481d39a73eeb11d6
+  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
@@ -236,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
@@ -246,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

metadata

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