gitlab-labkit 5.1.1 → 5.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dde258c9178baa3601cb15a3f3cad2b4470357c326e381a2aebb423de6f5235
-  data.tar.gz: c5fc0c320dc08937a789f1ebefb55adebd3905bc124ca813fea5de2d73efb102
+  metadata.gz: d272acd766a807cc483a70b13238a55b91dbffd0de51435c3e754df64562176d
+  data.tar.gz: 2fbc2ff23bbedca43ef1e5c650b3b6c78a0aa4c7ecfec85fec8eae79ef2d2752
 SHA512:
-  metadata.gz: f6dbd1b24464bdecc03635e2f9d3ebafe33003d755c9173d785a195982a0144dd7038db2078935925aa4aaa795f4f3bfba100a35a62a0daf0f457e3c12ee4113
-  data.tar.gz: 951f021de3fa71b9b61dbc44c2a6f057c5aedb21afc4367e1d2a7756e2f2bdcaee7edfbc44552113fe9358665f6ed94a118f6e5595fe01bc502b982fbc150e7b
+  metadata.gz: b469df64589bfe387e3d725d1cc6c6a3e769bc078ccb043b8afdf5f3591bae10a5730ecaa87069b1dc49041f50e6c6e92e145989a2a644e2d2f33fe56abd614f
+  data.tar.gz: 212bf5a04d9a38b4cd64f6b7319179dba2379f3b89b6b1c6070bf64f9f256ea899f6a02ddc35b271dcb6bfb300100627decd388b7b5e3ae5c45f289d2fdd4bfe

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.6"
+    GL_ASDF_RUBY_VERSION: "4.0.7"
     GL_ASDF_SHELLCHECK_VERSION: "0.11"
-    GL_ASDF_SHFMT_VERSION: "3.13"
+    GL_ASDF_SHFMT_VERSION: "3.14"

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@v5.15
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/standard-build@v5.24
 
   # 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@v5.15
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/ruby-build@v5.24
 
-  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v5.15
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v5.24
 
 # 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,
@@ -67,48 +67,21 @@ deploy:
     - Gemfile
     - .gitlab-ci.yml
 
-# Run the labkit-spec conformance harness with its Ruby server built from this
-# checkout. labkit-spec pins released SDKs, so this is the only pre-merge check
-# against the spec.
-conformance:
+# Gate SDK changes on the labkit-spec conformance suite, run remotely: trigger
+# a downstream pipeline in labkit-spec that checks out this pipeline's commit
+# (LABKIT_RUBY_SHA) and runs the Ruby conformance suite against it, verifying
+# structured-logging, lifecycle, and rate-limit parity with the spec.
+# strategy:depend mirrors the downstream result here, so a red run blocks the
+# merge. See https://gitlab.com/gitlab-org/theseus/theseus/-/work_items/30
+conformance-spec:
   stage: validate
-  image:
-    name: jdxcode/mise:2026.9.7
-    entrypoint: [""]
   needs: []
-  services:
-    - name: redis:8-alpine
-      alias: redis
+  variables:
+    LABKIT_RUBY_SHA: $CI_COMMIT_SHA
   rules:
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
-    - if: $CI_COMMIT_BRANCH
-      changes: !reference [.conformance-trigger-paths, changes]
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
       changes: !reference [.conformance-trigger-paths, changes]
-  variables:
-    LABKIT_SPEC_REPO: https://gitlab.com/gitlab-org/quality/tooling/labkit-spec.git
-    LABKIT_SPEC_REF: main
-    LABKIT_SPEC_DIR: $CI_PROJECT_DIR/.labkit-spec
-    MISE_TRUSTED_CONFIG_PATHS: $LABKIT_SPEC_DIR
-    MISE_DATA_DIR: $CI_PROJECT_DIR/.mise-cache
-    BUNDLE_PATH: vendor/bundle
-    CONFORMANCE_REDIS_ADDR: redis:6379
-  cache:
-    key: conformance-servers
-    paths:
-      - .labkit-spec/conformance/servers/ruby/vendor/
-      - .mise-cache/
-  script:
-    # Not clone: the restored cache makes LABKIT_SPEC_DIR non-empty.
-    - git init -q "$LABKIT_SPEC_DIR"
-    - git -C "$LABKIT_SPEC_DIR" fetch -q --depth 1 "$LABKIT_SPEC_REPO" "$LABKIT_SPEC_REF"
-    - git -C "$LABKIT_SPEC_DIR" checkout -q FETCH_HEAD
-    - cd "$LABKIT_SPEC_DIR"
-    - mise install
-    # The gemspec lists files via `git ls-files`, so the path must be a git work tree.
-    # grep fails the job if the Gemfile line moved and sed matched nothing.
-    - |
-      sed -i 's|^gem "gitlab-labkit".*|gem "gitlab-labkit", path: "'"$CI_PROJECT_DIR"'"|' conformance/servers/ruby/Gemfile
-      grep -q 'gem "gitlab-labkit", path: "'"$CI_PROJECT_DIR"'"' conformance/servers/ruby/Gemfile
-    - mise run conformance:ruby
-  timeout: 15m
+  trigger:
+    project: gitlab-org/quality/tooling/labkit-spec
+    branch: main
+    strategy: depend

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: v5.15  # renovate:managed
+    rev: v5.24  # renovate:managed
 
     hooks:
       - id: shellcheck  # Run shellcheck for changed Shell files

data/.tool-versions

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

data/README.md

@@ -55,13 +55,16 @@ To opt out of autostart (e.g. you've started Redis some other way), set
 `LABKIT_TEST_REDIS_URL` to a reachable instance, or
 `LABKIT_TEST_REDIS_NO_AUTOSTART=1` to fail loudly instead of spawning.
 
-The `conformance` CI job runs the
+The `conformance-spec` CI job gates merge requests on the
 [labkit-spec](https://gitlab.com/gitlab-org/quality/tooling/labkit-spec)
-conformance harness against the spec's Ruby server, with the `gitlab-labkit`
-gem installed from your branch instead of the released version. A change to
-logging, lifecycle, or rate limiting is therefore checked against the
-cross-SDK scenarios before it merges. To run it locally, clone labkit-spec and
-replace the `gitlab-labkit` line in `conformance/servers/ruby/Gemfile` with
+conformance harness. It triggers a downstream pipeline in labkit-spec that
+checks out the MR's commit and runs the Ruby conformance suite against it,
+with the `gitlab-labkit` gem installed from that checkout instead of the
+released version. A change to logging, lifecycle, or rate limiting is
+therefore checked against the cross-SDK scenarios before it merges, and the
+downstream result is mirrored here, so a red run blocks the merge. To run it
+locally, clone labkit-spec and replace the `gitlab-labkit` line in
+`conformance/servers/ruby/Gemfile` with
 
 ```ruby
 gem "gitlab-labkit", path: "/path/to/labkit-ruby"
@@ -71,10 +74,9 @@ then run `mise run conformance:ruby` from the spec checkout (the rate-limit
 aspect needs Docker or `CONFORMANCE_REDIS_ADDR`).
 
 If your change also needs a labkit-spec change (a new scenario, or an update
-to its Ruby server), open that MR first and point `LABKIT_SPEC_REF` in
-`.gitlab-ci.yml` at its branch so this job validates both together. Set it
-back to `main` once the spec MR merges; a non-`main` ref must not reach
-`master`.
+to its Ruby server), open and merge that MR first. The trigger always runs
+labkit-spec `main`, so the spec side has to land before the gate here can
+pass.
 
 Please also review the [development section of the LabKit (go) README](https://gitlab.com/gitlab-org/labkit#developing-labkit) for details of the LabKit architectural philosophy.
 

data/lib/labkit/rate_limit/README.md

@@ -469,7 +469,7 @@ result.to_response_headers
 | `resolved_limit`  | The evaluated `Integer` limit for this check.                    |
 | `resolved_period` | The evaluated `Integer` period in seconds for this check.        |
 | `count`           | Raw INCR value; useful for utilization-ratio metrics.            |
-| `remaining`       | `[resolved_limit - count, 0].max`.                               |
+| `remaining`       | `resolved_limit - count`, clamped to `[0, max(resolved_limit, 0)]`. |
 | `reset_at`        | Best-effort UTC `Time` when the window resets (advisory only).   |
 
 `to_response_headers` returns `{}` for an unmatched or error result, so it is
@@ -483,6 +483,10 @@ 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 negative `cost:` takes the same path: it would credit quota back, so `check`
+refuses it before touching any rule. Nothing is counted and the WARN line
+carries `rule: null`.
+
 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
@@ -514,7 +518,6 @@ flooding).
 | `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_peeks_total`            | counter | `rate_limiter`, `error`                      | Exactly one increment per `peek` call, including fail-open. `error` is `"true"`/`"false"`. |
-| `gitlab_labkit_rate_limiter_enforced_total`         | counter | `rate_limiter`, `rule`                       | One increment per request the caller rejected on a `:block`. Emitted by the caller, not the evaluator: a rollout gate may observe a block without enforcing it. |
 | `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.                                   |
 

data/lib/labkit/rate_limit/evaluator.rb

@@ -120,6 +120,9 @@ module Labkit
 
       def check(identifier, cost: 1, rule_context: nil)
         cursor = RuleCursor.new
+        # A negative cost would credit quota back and open the window for good.
+        raise ArgumentError, "cost is #{cost}, must not be negative" if cost.negative?
+
         result = check_rules(identifier, cost, rule_context, cursor)
       rescue StandardError => e
         # Intentionally broad: fail-open applies to any unexpected error (network,
@@ -372,7 +375,7 @@ module Labkit
           count: count,
           # A ban outlives its counter, so count reads 0 once the window has
           # gone. Nothing is remaining while the ban still blocks.
-          remaining: banned ? 0 : [resolved_limit - count, 0].max,
+          remaining: banned ? 0 : remaining_of(resolved_limit, count),
           reset_at: Time.now.utc + (banned ? ban_ttl : window_remaining)
         )
 
@@ -383,13 +386,21 @@ module Labkit
         info = Result::Info.new(
           resolved_limit: resolved_limit, resolved_period: resolved_period,
           count: count,
-          remaining: [resolved_limit - count, 0].max,
+          remaining: remaining_of(resolved_limit, count),
           reset_at: Time.now.utc + (ttl >= 0 ? ttl : resolved_period)
         )
 
         Result::Evaluation.new(rule: rule, exceeded: count > resolved_limit, info: info)
       end
 
+      # RateLimit-Remaining must not exceed RateLimit-Limit, and a counter can
+      # sit below zero if an older client credited it. A limit resolving to a
+      # non-positive value means "deny all", so the ceiling floors at zero too.
+      def remaining_of(resolved_limit, count)
+        ceiling = [resolved_limit, 0].max
+        (ceiling - count).clamp(0, ceiling)
+      end
+
       # The braces are the cluster hash tag: a counter and its ban must share a
       # slot because BAN_SCRIPT touches both in one call. The rule name stays
       # inside it so one identifier's keys spread across nodes instead of piling

data/lib/labkit/rate_limit/limiter.rb

@@ -35,6 +35,8 @@ module Labkit
       # @param cost [Numeric] amount to add to the counter. Defaults to 1
       #   (count-mode). Pass a non-1 Numeric for cost-mode counters such as
       #   resource-usage limits; passing 0 reads the counter without writing.
+      #   A negative cost would credit quota back, so the check fails open and
+      #   logs instead of counting.
       # @param rule_context [Hash, nil] optional per-request context passed to
       #   one-arity callables on +limit+/+period+. Lets rules resolve dynamic
       #   configuration (e.g. per-namespace settings) without rebuilding the

data/lib/labkit/rate_limit/metrics.rb

@@ -71,16 +71,6 @@ module Labkit
         )
       end
 
-      # Emitted by the caller, once per rejected request: only the caller knows
-      # whether it acted on a :block (a rollout gate may observe without enforcing).
-      def enforced_total
-        Labkit::Metrics::Client.counter(
-          :gitlab_labkit_rate_limiter_enforced_total,
-          'Total number of requests rejected on a rate limit block',
-          { rate_limiter: nil, rule: nil }
-        )
-      end
-
       def limit_gauge
         Labkit::Metrics::Client.gauge(
           :gitlab_labkit_rate_limiter_limit,

data/lib/labkit/rate_limit/result.rb

@@ -169,8 +169,10 @@ module Labkit
     #                   for default cost=1 callers, fractional for cost-mode callers.
     #                   Pre-2.x releases exposed this as Integer; see the migration
     #                   note in the cost-aware Lua script change.
-    # remaining       - requests remaining before the limit is hit (floors at 0).
-    #                   Inherits Float typing from count when count is fractional.
+    # remaining       - requests remaining before the limit is hit, clamped to
+    #                   [0, resolved_limit]; 0 throughout when the limit is
+    #                   non-positive. Inherits Float typing from count when
+    #                   count is fractional.
     # reset_at        - best-effort UTC Time when the counter window resets
     Result::Info = Data.define(:resolved_limit, :resolved_period, :count, :remaining, :reset_at)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 5.1.1
+  version: 5.1.2
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -722,7 +722,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Instrumentation for GitLab
 test_files: []