gitlab-labkit 5.5.0 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fe9b7fbeed18b9aced46d0f50b8e0aeeb4442a164818ed00f581a39559a2203
-  data.tar.gz: 5362ebd8bd9d8f3cf598dd473be4a1078ed1b5eda9e11723c6bba35e5b5ad62c
+  metadata.gz: fb00f476a5fed0be71839727d4fb5d8230f773831c8c8cca40ff8090c76cb2c5
+  data.tar.gz: c382bf0eed9e55b283eb90c3956a00c8dbf73ad5819fb22e8dd6a1be931fd9ff
 SHA512:
-  metadata.gz: a8e09616bd24dc1e5b619ae05c426451ef0b1cb40305832dfd52b04e801cd2f490823cb45592e101469f3cee4edca5a4f6d2190ddcfbded59e0e1282fc5fe01a
-  data.tar.gz: 5103ce4264e6fca52740485de4c81e17feedeb31c493b2aaeda35a0ecdedbd47c043ec77a15371a1eb949a48c8341393c4fc09bee5458d958de83b195315def8
+  metadata.gz: 5932210330aa7c8c4413de43f8ae710508658846c89f1b7b74e1d8d36af564b61034988a6248bf9795d6343602d4b1579d6a9aff48795cda1163c545377932b9
+  data.tar.gz: ddc501d350806e384f122f152f6ceb7066487bc4f41078341f1ae13373631adf52a1f5cd427a69e879482cf3dc1dff75bbfe7cd57dd1237094c595e615acc591

data/.gitlab/CODEOWNERS

@@ -1 +1 @@
-* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @sankalp_gl @hardikgala @nindurkar @ashs2
+* @reprazent @mkaeppler @ayufan @hmerscher @sankalp_gl @hardikgala @nindurkar @ashs2

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 @ayufan @hmerscher @e_forbes @M_Alvarez @mwoolf @sankalp_gl @hardikgala @nindurkar @ashs2
+* @reprazent @ayufan @hmerscher @e_forbes @M_Alvarez @mwoolf @sankalp_gl @hardikgala @nindurkar @ashs2

data/lib/labkit/rate_limit/README.md

@@ -512,7 +512,8 @@ result.degraded?          # => true if a matched count_distinct rule was skipped
 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>" }
+# => { "RateLimit-Name" => "<rule name>", "RateLimit-Limit" => "...", "RateLimit-Observed" => "...",
+#      "RateLimit-Remaining" => "...", "RateLimit-Reset" => "<unix-ts>" }
 ```
 
 `Result::Info` holds the per-window counter snapshot:
@@ -528,6 +529,27 @@ result.to_response_headers
 `to_response_headers` returns `{}` for an unmatched or error result, so it is
 safe to merge unconditionally.
 
+### Response headers
+
+`Result#to_response_headers` reports the most constraining evaluation.
+`Result::Evaluation#to_response_headers` builds the same headers for one evaluation, for a caller that picks its own evaluation across several results.
+
+| header                | present           | value                                               |
+|-----------------------|-------------------|-----------------------------------------------------|
+| `RateLimit-Name`      | always            | The rule's `name`.                                  |
+| `RateLimit-Limit`     | always            | `resolved_limit` in the rule's period, at least 0.  |
+| `RateLimit-Observed`  | always            | `count`, as an Integer, at least 0.                 |
+| `RateLimit-Remaining` | always            | `remaining`, as an Integer.                         |
+| `RateLimit-Reset`     | always            | `reset_at` as a Unix timestamp.                     |
+| `Retry-After`         | blocking only     | Seconds to `reset_at`, rounded up, at least 0.      |
+| `RateLimit-ResetTime` | blocking only     | `reset_at` as an HTTP date.                         |
+
+`Retry-After` and `RateLimit-ResetTime` belong on the 429, so they appear only when the evaluation blocks.
+For a rule with `ban_for`, `reset_at` is the end of the ban, so these headers report when the ban lifts.
+
+`RateLimit-Limit`, `RateLimit-Observed` and `RateLimit-Remaining` all count within the rule's `period`.
+The headers do not state the period, so a client that needs it must know the rule.
+
 ## Fail-open
 
 The evaluator wraps `check` and `peek` in a broad rescue. Any `StandardError`

data/lib/labkit/rate_limit/result.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "time" # Time#httpdate
+
 module Labkit
   module RateLimit
     # Result is the return value of Limiter#check.
@@ -113,18 +115,13 @@ module Labkit
         @most_constraining ||= @evaluations.min
       end
 
-      # Returns RFC-compliant rate limit response headers, or {} when no rule matched or an error occurred.
-      # Keys: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (Unix timestamp).
-      # remaining is coerced to Integer for header output even when info.remaining is fractional;
-      # the RateLimit header spec requires integer values.
+      # Returns the rate limit response headers of the most constraining
+      # evaluation, or {} when no rule matched, a :skip rule matched, or an
+      # error occurred. See Result::Evaluation#to_response_headers for the keys.
       def to_response_headers
         return {} unless matched? && !error? && info
 
-        {
-          "RateLimit-Limit" => info.resolved_limit.to_i.to_s,
-          "RateLimit-Remaining" => info.remaining.to_i.to_s,
-          "RateLimit-Reset" => info.reset_at.to_i.to_s
-        }
+        most_constraining.to_response_headers
       end
     end
 
@@ -155,6 +152,32 @@ module Labkit
         constraint_rank <=> other.constraint_rank
       end
 
+      # Returns the rate limit response headers for this evaluation. Values are
+      # Strings, and counts are coerced to Integer because the RateLimit header
+      # spec requires integer values even when count is fractional.
+      #
+      # RateLimit-Name (the rule name), RateLimit-Limit, RateLimit-Observed,
+      # RateLimit-Remaining and RateLimit-Reset (Unix timestamp) are always
+      # present. Limit, Observed and Remaining all count within the rule's own
+      # period. A blocking evaluation also gets Retry-After (seconds) and
+      # RateLimit-ResetTime (HTTP date), which belong on the 429.
+      def to_response_headers
+        headers = {}
+        headers["RateLimit-Name"] = rule.name
+        # Floored at 0 like remaining: a callable limit can resolve below zero
+        # to deny all, and an older client could credit a counter below zero.
+        headers["RateLimit-Limit"] = [info.resolved_limit.to_i, 0].max.to_s
+        headers["RateLimit-Observed"] = [info.count.to_i, 0].max.to_s
+        headers["RateLimit-Remaining"] = info.remaining.to_i.to_s
+        headers["RateLimit-Reset"] = info.reset_at.to_i.to_s
+        return headers unless block?
+
+        # Rounded up so a client that honours it does not retry before the reset.
+        headers["Retry-After"] = [(info.reset_at - Time.now.utc).ceil, 0].max.to_s
+        headers["RateLimit-ResetTime"] = info.reset_at.httpdate
+        headers
+      end
+
       protected
 
       def constraint_rank

metadata

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